🔎 feat: Add Prompt and Agent Permissions Migration Checks (#9063)

* chore: fix mock typing in packages/api tests

* chore: improve imports, type handling and method signatures for MCPServersRegistry

* chore: use enum in migration scripts

* chore: ParsedServerConfig type to enhance server configuration handling

* feat: Implement agent permissions migration check and logging

* feat: Integrate migration checks into server initialization process

* feat: Add prompt permissions migration check and logging to server initialization

* chore: move prompt formatting functions to dedicated prompts dir

packages/api/src/prompts/format.ts

@@ -0,0 +1,150 @@
+import { SystemCategories } from 'librechat-data-provider';
+import type { IPromptGroupDocument as IPromptGroup } from '@librechat/data-schemas';
+import type { Types } from 'mongoose';
+import type { PromptGroupsListResponse } from '~/types';
+
+/**
+ * Formats prompt groups for the paginated /groups endpoint response
+ */
+export function formatPromptGroupsResponse({
+  promptGroups = [],
+  pageNumber,
+  pageSize,
+  actualLimit,
+  hasMore = false,
+  after = null,
+}: {
+  promptGroups: IPromptGroup[];
+  pageNumber?: string;
+  pageSize?: string;
+  actualLimit?: string | number;
+  hasMore?: boolean;
+  after?: string | null;
+}): PromptGroupsListResponse {
+  const effectivePageSize = parseInt(pageSize || '') || parseInt(String(actualLimit || '')) || 10;
+  const totalPages =
+    promptGroups.length > 0 ? Math.ceil(promptGroups.length / effectivePageSize).toString() : '0';
+
+  return {
+    promptGroups,
+    pageNumber: pageNumber || '1',
+    pageSize: pageSize || String(actualLimit) || '10',
+    pages: totalPages,
+    has_more: hasMore,
+    after,
+  };
+}
+
+/**
+ * Creates an empty response for the paginated /groups endpoint
+ */
+export function createEmptyPromptGroupsResponse({
+  pageNumber,
+  pageSize,
+  actualLimit,
+}: {
+  pageNumber?: string;
+  pageSize?: string;
+  actualLimit?: string | number;
+}): PromptGroupsListResponse {
+  return {
+    promptGroups: [],
+    pageNumber: pageNumber || '1',
+    pageSize: pageSize || String(actualLimit) || '10',
+    pages: '0',
+    has_more: false,
+    after: null,
+  };
+}
+
+/**
+ * Marks prompt groups as public based on the publicly accessible IDs
+ */
+export function markPublicPromptGroups(
+  promptGroups: IPromptGroup[],
+  publiclyAccessibleIds: Types.ObjectId[],
+): IPromptGroup[] {
+  if (!promptGroups.length) {
+    return [];
+  }
+
+  return promptGroups.map((group) => {
+    const isPublic = publiclyAccessibleIds.some((id) => id.equals(group._id?.toString()));
+    return isPublic ? ({ ...group, isPublic: true } as IPromptGroup) : group;
+  });
+}
+
+/**
+ * Builds filter object for prompt group queries
+ */
+export function buildPromptGroupFilter({
+  name,
+  category,
+  ...otherFilters
+}: {
+  name?: string;
+  category?: string;
+  [key: string]: string | number | boolean | RegExp | undefined;
+}): {
+  filter: Record<string, string | number | boolean | RegExp | undefined>;
+  searchShared: boolean;
+  searchSharedOnly: boolean;
+} {
+  const filter: Record<string, string | number | boolean | RegExp | undefined> = {
+    ...otherFilters,
+  };
+  let searchShared = true;
+  let searchSharedOnly = false;
+
+  // Handle name filter - convert to regex for case-insensitive search
+  if (name) {
+    const escapeRegExp = (str: string) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    filter.name = new RegExp(escapeRegExp(name), 'i');
+  }
+
+  // Handle category filters with special system categories
+  if (category === SystemCategories.MY_PROMPTS) {
+    searchShared = false;
+  } else if (category === SystemCategories.NO_CATEGORY) {
+    filter.category = '';
+  } else if (category === SystemCategories.SHARED_PROMPTS) {
+    searchSharedOnly = true;
+  } else if (category) {
+    filter.category = category;
+  }
+
+  return { filter, searchShared, searchSharedOnly };
+}
+
+/**
+ * Filters accessible IDs based on shared/public prompts logic
+ */
+export async function filterAccessibleIdsBySharedLogic({
+  accessibleIds,
+  searchShared,
+  searchSharedOnly,
+  publicPromptGroupIds,
+}: {
+  accessibleIds: Types.ObjectId[];
+  searchShared: boolean;
+  searchSharedOnly: boolean;
+  publicPromptGroupIds?: Types.ObjectId[];
+}): Promise<Types.ObjectId[]> {
+  const publicIdStrings = new Set((publicPromptGroupIds || []).map((id) => id.toString()));
+
+  if (!searchShared) {
+    // For MY_PROMPTS - exclude public prompts to show only user's own prompts
+    return accessibleIds.filter((id) => !publicIdStrings.has(id.toString()));
+  }
+
+  if (searchSharedOnly) {
+    // Handle SHARED_PROMPTS filter - only return public prompts that user has access to
+    if (!publicPromptGroupIds?.length) {
+      return [];
+    }
+    const accessibleIdStrings = new Set(accessibleIds.map((id) => id.toString()));
+    return publicPromptGroupIds.filter((id) => accessibleIdStrings.has(id.toString()));
+  }
+
+  return [...accessibleIds, ...(publicPromptGroupIds || [])];
+}

packages/api/src/prompts/index.ts

@@ -0,0 +1,2 @@
+export * from './format';
+export * from './migration';

packages/api/src/prompts/migration.ts

@@ -0,0 +1,223 @@
+import { logger } from '@librechat/data-schemas';
+import { AccessRoleIds, ResourceType, PrincipalType, Constants } from 'librechat-data-provider';
+import type { AccessRoleMethods, IPromptGroupDocument } from '@librechat/data-schemas';
+import type { Model } from 'mongoose';
+
+const { GLOBAL_PROJECT_NAME } = Constants;
+
+export interface PromptMigrationCheckDbMethods {
+  findRoleByIdentifier: AccessRoleMethods['findRoleByIdentifier'];
+  getProjectByName: (
+    projectName: string,
+    fieldsToSelect?: string[] | null,
+  ) => Promise<{
+    promptGroupIds?: string[];
+    [key: string]: unknown;
+  } | null>;
+}
+
+export interface PromptMigrationCheckParams {
+  db: PromptMigrationCheckDbMethods;
+  PromptGroupModel: Model<IPromptGroupDocument>;
+}
+
+interface PromptGroupMigrationData {
+  _id: string;
+  name: string;
+  author: string;
+  authorName?: string;
+  category?: string;
+}
+
+export interface PromptMigrationCheckResult {
+  totalToMigrate: number;
+  globalViewAccess: number;
+  privateGroups: number;
+  details?: {
+    globalViewAccess: Array<{ name: string; _id: string; category: string }>;
+    privateGroups: Array<{ name: string; _id: string; category: string }>;
+  };
+}
+
+/**
+ * Check if prompt groups need to be migrated to the new permission system
+ * This performs a dry-run check similar to the migration script
+ */
+export async function checkPromptPermissionsMigration({
+  db,
+  PromptGroupModel,
+}: PromptMigrationCheckParams): Promise<PromptMigrationCheckResult> {
+  logger.debug('Checking if prompt permissions migration is needed');
+
+  try {
+    // Verify required roles exist
+    const ownerRole = await db.findRoleByIdentifier(AccessRoleIds.PROMPTGROUP_OWNER);
+    const viewerRole = await db.findRoleByIdentifier(AccessRoleIds.PROMPTGROUP_VIEWER);
+    const editorRole = await db.findRoleByIdentifier(AccessRoleIds.PROMPTGROUP_EDITOR);
+
+    if (!ownerRole || !viewerRole || !editorRole) {
+      logger.warn(
+        'Required promptGroup roles not found. Permission system may not be fully initialized.',
+      );
+      return {
+        totalToMigrate: 0,
+        globalViewAccess: 0,
+        privateGroups: 0,
+      };
+    }
+
+    // Get global project prompt group IDs
+    const globalProject = await db.getProjectByName(GLOBAL_PROJECT_NAME, ['promptGroupIds']);
+    const globalPromptGroupIds = new Set(
+      (globalProject?.promptGroupIds || []).map((id) => id.toString()),
+    );
+
+    // Find promptGroups without ACL entries (no batching for efficiency on startup)
+    const promptGroupsToMigrate: PromptGroupMigrationData[] = await PromptGroupModel.aggregate([
+      {
+        $lookup: {
+          from: 'aclentries',
+          localField: '_id',
+          foreignField: 'resourceId',
+          as: 'aclEntries',
+        },
+      },
+      {
+        $addFields: {
+          promptGroupAclEntries: {
+            $filter: {
+              input: '$aclEntries',
+              as: 'aclEntry',
+              cond: {
+                $and: [
+                  { $eq: ['$$aclEntry.resourceType', ResourceType.PROMPTGROUP] },
+                  { $eq: ['$$aclEntry.principalType', PrincipalType.USER] },
+                ],
+              },
+            },
+          },
+        },
+      },
+      {
+        $match: {
+          author: { $exists: true, $ne: null },
+          promptGroupAclEntries: { $size: 0 },
+        },
+      },
+      {
+        $project: {
+          _id: 1,
+          name: 1,
+          author: 1,
+          authorName: 1,
+          category: 1,
+        },
+      },
+    ]);
+
+    const categories: {
+      globalViewAccess: PromptGroupMigrationData[];
+      privateGroups: PromptGroupMigrationData[];
+    } = {
+      globalViewAccess: [],
+      privateGroups: [],
+    };
+
+    promptGroupsToMigrate.forEach((group) => {
+      const isGlobalGroup = globalPromptGroupIds.has(group._id.toString());
+
+      if (isGlobalGroup) {
+        categories.globalViewAccess.push(group);
+      } else {
+        categories.privateGroups.push(group);
+      }
+    });
+
+    const result: PromptMigrationCheckResult = {
+      totalToMigrate: promptGroupsToMigrate.length,
+      globalViewAccess: categories.globalViewAccess.length,
+      privateGroups: categories.privateGroups.length,
+    };
+
+    // Add details for debugging
+    if (promptGroupsToMigrate.length > 0) {
+      result.details = {
+        globalViewAccess: categories.globalViewAccess.map((g) => ({
+          name: g.name,
+          _id: g._id.toString(),
+          category: g.category || 'uncategorized',
+        })),
+        privateGroups: categories.privateGroups.map((g) => ({
+          name: g.name,
+          _id: g._id.toString(),
+          category: g.category || 'uncategorized',
+        })),
+      };
+    }
+
+    logger.debug('Prompt migration check completed', {
+      totalToMigrate: result.totalToMigrate,
+      globalViewAccess: result.globalViewAccess,
+      privateGroups: result.privateGroups,
+    });
+
+    return result;
+  } catch (error) {
+    logger.error('Failed to check prompt permissions migration', error);
+    // Return zero counts on error to avoid blocking startup
+    return {
+      totalToMigrate: 0,
+      globalViewAccess: 0,
+      privateGroups: 0,
+    };
+  }
+}
+
+/**
+ * Log migration warning to console if prompt groups need migration
+ */
+export function logPromptMigrationWarning(result: PromptMigrationCheckResult): void {
+  if (result.totalToMigrate === 0) {
+    return;
+  }
+
+  // Create a visible warning box
+  const border = '='.repeat(80);
+  const warning = [
+    '',
+    border,
+    '                   IMPORTANT: PROMPT PERMISSIONS MIGRATION REQUIRED',
+    border,
+    '',
+    `  Total prompt groups to migrate: ${result.totalToMigrate}`,
+    `  - Global View Access: ${result.globalViewAccess} prompt groups`,
+    `  - Private Prompt Groups: ${result.privateGroups} prompt groups`,
+    '',
+    '  The new prompt sharing system requires migrating existing prompt groups.',
+    '  Please run the following command to migrate your prompts:',
+    '',
+    '    npm run migrate:prompt-permissions',
+    '',
+    '  For a dry run (preview) of what will be migrated:',
+    '',
+    '    npm run migrate:prompt-permissions:dry-run',
+    '',
+    '  This migration will:',
+    '  1. Grant owner permissions to prompt authors',
+    '  2. Set public view permissions for prompts in the global project',
+    '  3. Keep private prompts accessible only to their authors',
+    '',
+    border,
+    '',
+  ];
+
+  // Use console methods directly for visibility
+  console.log('\n' + warning.join('\n') + '\n');
+
+  // Also log with logger for consistency
+  logger.warn('Prompt permissions migration required', {
+    totalToMigrate: result.totalToMigrate,
+    globalViewAccess: result.globalViewAccess,
+    privateGroups: result.privateGroups,
+  });
+}