📜 feat: Implement System Grants for Capability-Based Authorization

[danny-avila]

Summary

Closes #10197

Replaces all hardcoded SystemRoles.ADMIN role checks throughout the codebase with a database-driven, capability-based authorization system built around a new SystemGrant collection.

• Introduced SystemCapabilities constants (access:admin, manage:users, manage:prompts, etc.) and a ResourceCapabilityMap that maps each ResourceType to its corresponding management capability, owned by @librechat/data-schemas and re-exported as needed.
• Added a SystemGrant Mongoose schema, model, and type definitions in data-schemas, with a compound unique index on (principalType, principalId, capability, tenantId) to enforce per-principal, per-tenant uniqueness. principalType is validated against the PrincipalType enum at the schema level; capability is validated against base capability values plus section-level and assign-scoped patterns. principalType is typed as the PrincipalType enum throughout for compile-time safety.
• Extracted a normalizePrincipalId utility to packages/data-schemas/src/utils/principal.ts that casts string user/group IDs to ObjectId while leaving role name strings unchanged, with an explicit Types.ObjectId.isValid() guard that throws a TypeError on invalid input rather than propagating a raw BSON error. Applied consistently across grantCapability, revokeCapability, and getCapabilitiesForPrincipal.
• Implemented createSystemGrantMethods in data-schemas, exposing grantCapability, revokeCapability, hasCapabilityForPrincipals, getCapabilitiesForPrincipal, and seedSystemGrants — all tenant-aware, session-capable, and using normalizePrincipalId to guarantee write/read symmetry. grantCapability catches E11000 on concurrent duplicate upserts and returns the existing document instead of throwing, making it safe under parallel load. A module-level reverse implication map is precomputed at load time so hasCapabilityForPrincipals resolves implication lookups in O(1) instead of iterating the full map on every call.
• Built a generateCapabilityCheck DI factory in @librechat/api that produces hasCapability, requireCapability, and hasConfigCapability helpers, following the same pattern as the existing generateCheckAccess. ResolvedPrincipal.principalType is typed as PrincipalType to match the implementation signature of hasCapabilityForPrincipals.
• Added explicit guards in requireCapability: returns 401 when req.user is absent and when both req.user.id and req.user._id are falsy, preventing any downstream DB call on malformed auth state.
• Added a per-request AsyncLocalStorage cache (capabilityContextMiddleware) that deduplicates getUserPrincipals and hasCapabilityForPrincipals calls within a single request. Outside a request context (background jobs, tests), the store is absent and every call falls through to the database — correct behavior with no code changes required at call sites.
• Wired the factory to the live DB methods in api/server/middleware/roles/capabilities.js and re-exported through api/server/middleware/index.js. Registered capabilityContextMiddleware globally at app startup before any route.
• Migrated capability checks across canDeleteAccount, validateAuthor, canAccessResource, fetchAssistants, and routes for roles, prompts, files, and admin auth, replacing each role === SystemRoles.ADMIN guard with the appropriate hasCapability or requireCapability call. All inline hasCapability calls are wrapped in try-catch with deny-by-default fallback and a single-argument logger.warn on failure for consistent observability. canDeleteAccount checks ACCESS_ADMIN (not MANAGE_USERS) so only principals with explicit system-admin access can bypass the account deletion policy.
• Removed author and role parameters from deletePrompt and deletePromptGroup in data-schemas, delegating authorization entirely to upstream ACL middleware. Both functions are documented with explicit @throws-style JSDoc noting that callers must enforce access before invoking them.
• Added seedSystemGrants() to the startup database seeding sequence, granting all SystemCapabilities to the ADMIN role idempotently on every boot via a single bulkWrite with ordered: false for concurrency safety across parallel instances (K8s rolling deploys, PM2 cluster). Seeding retries up to three times with exponential backoff on transient failures; after exhausting retries it logs an actionable error message including a manual recovery command and continues startup rather than crashing.

Note: This PR establishes the authorization checking and data layer only. No API endpoints for granting or revoking capabilities are included here — those will be added in a follow-up PR. Until then, the system operates with ADMIN holding all capabilities (seeded at startup) and any custom grants applied directly via DB or future endpoints.

Change Type

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Testing

New and updated tests cover all introduced logic with an in-memory MongoDB server (mongodb-memory-server):

• packages/api/src/middleware/capabilities.spec.ts — unit tests for generateCapabilityCheck, covering hasCapability, requireCapability (401 on missing user, 401 on missing id, 403 on missing capability, 500 on error), and hasConfigCapability (broad → section-specific fallback).
• api/server/middleware/roles/capabilities.spec.js — mirrors the above against the wired JS module.
• api/server/services/systemGrant.spec.js — integration tests for all createSystemGrantMethods functions, including seedSystemGrants idempotency, grantCapability upsert deduplication, revokeCapability, hasCapabilityForPrincipals across user/role/group principals, tenant scoping isolation, and a dedicated principalId normalization suite that verifies string-input grants are found, revoked, and listed correctly via ObjectId-based queries.
• api/server/middleware/accessResources/canAccessMCPServerResource.spec.js and api/server/routes/files/files.agents.test.js — updated to seed SystemGrant entries for the ADMIN role before asserting capability-based bypass behavior.
• api/server/routes/prompts.test.js — seeds MANAGE_PROMPTS and READ_PROMPTS grants for the ADMIN role to validate the updated prompt route logic.
• packages/data-schemas/src/methods/prompt.spec.ts — updated deletePrompt call to remove the now-dropped author/role parameters.

Test Configuration:

All tests run against mongodb-memory-server with no external dependencies. Run with jest from either the packages/data-schemas, packages/api, or api workspace roots.

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes
• Any changes dependent on mine have been merged and published in downstream modules.

[Copilot]

Pull request overview

This pull request introduces a comprehensive capability-based authorization system to replace direct role-based checks throughout the codebase. The system enables fine-grained permission management through SystemGrant entities that map capabilities (like MANAGE_PROMPTS, READ_USERS, etc.) to principals (users, groups, or roles).

Changes:

• Introduces SystemGrant data model with schema, types, and CRUD methods for managing system-level capabilities
• Adds capability checking middleware (hasCapability, requireCapability, hasConfigCapability) that integrates with the existing ACL permission system
• Migrates authorization checks from hardcoded SystemRoles.ADMIN comparisons to capability-based checks across routes for roles, prompts, files, assistants, and admin auth
• Updates existing ACL resource access middleware to support capability-based admin bypass via ResourceCapabilityMap
• Removes author and role parameters from prompt deletion methods since authorization is now handled by ACL middleware
• Seeds ADMIN role with all system capabilities on startup

Reviewed changes

Copilot reviewed 31 out of 31 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/data-schemas/src/types/systemGrant.ts	Defines SystemGrant type with principal, capability, tenant scoping, and audit fields
packages/data-schemas/src/schema/systemGrant.ts	Mongoose schema with unique index on principal+capability+tenant combination
packages/data-schemas/src/models/systemGrant.ts	Model factory for SystemGrant
packages/data-schemas/src/methods/systemGrant.ts	CRUD operations: grant/revoke capabilities, check capabilities for principals, seed admin grants
packages/data-provider/src/systemCapabilities.ts	Defines all system capabilities and ResourceCapabilityMap for ACL integration
packages/api/src/middleware/capabilities.ts	Dependency-injected capability checking functions for routes
packages/api/src/middleware/capabilities.spec.ts	Tests for capability middleware factory
api/server/middleware/roles/capabilities.js	Wires capability checks to database methods
api/server/routes/roles.js	Migrates role management endpoints from checkAdmin to requireCapability
api/server/routes/prompts.js	Uses hasCapability for READ_PROMPTS and MANAGE_PROMPTS checks
api/server/routes/files/files.js	Replaces admin role check with MANAGE_AGENTS capability for file uploads
api/server/routes/admin/auth.js	Uses requireCapability(ACCESS_ADMIN) instead of requireAdmin
api/server/middleware/canDeleteAccount.js	Checks MANAGE_USERS capability for account deletion
api/server/middleware/assistants/validateAuthor.js	Uses MANAGE_ASSISTANTS capability
api/server/middleware/accessResources/canAccessResource.js	Integrates capability bypass via ResourceCapabilityMap
api/server/controllers/assistants/helpers.js	Uses MANAGE_ASSISTANTS capability for assistant listing
packages/data-schemas/src/methods/prompt.ts	Removes author/role parameters from deletePrompt and deletePromptGroup
api/models/index.js	Adds seedSystemGrants to database initialization
Test files	Updates tests to seed SystemGrant entries and verify capability-based access control

Comments suppressed due to low confidence (1)

packages/data-provider/src/systemCapabilities.ts:71

• The ISystemGrant interface defined here appears to be unused and duplicates the ISystemGrant type in data-schemas with incompatible type signatures (principalId is string here but string | Types.ObjectId in data-schemas, grantedAt is required here but optional in data-schemas). This could cause confusion. Consider removing this duplicate interface or documenting why it exists if it serves as an API contract type.

export interface ISystemGrant {
  principalType: string;
  principalId: string;
  capability: SystemCapability;
  tenantId?: string;
  grantedBy?: string;
  grantedAt: Date;
}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (5)

packages/api/src/middleware/capabilities.ts:98

• requireCapability constructs user.id from req.user.id ?? req.user._id?.toString(), but doesn’t validate that an id was actually found. If a request reaches this middleware with a user object missing both fields, getUserPrincipals will throw (e.g., when it tries to construct an ObjectId). Consider returning 401 (or 500) when the computed id is falsy before calling hasCapability.

        const user: CapabilityUser = {
          id: req.user.id ?? req.user._id?.toString(),
          role: req.user.role ?? '',
          tenantId: (req.user as CapabilityUser).tenantId,
        };

packages/data-schemas/src/types/systemGrant.ts:8

• The new SystemGrant type uses principalType: string, but the rest of the access-control types (e.g., AclEntry) use the PrincipalType enum from librechat-data-provider for stronger typing and consistency. Consider changing principalType to PrincipalType (and updating the doc comment accordingly) to prevent invalid values from being passed around.
  packages/data-schemas/src/methods/transaction.spec.ts:1007
• These assertions were changed to optional-chain the queried document (Balance.findOne(...)). That weakens the test signal: if the document is unexpectedly null, the matcher will fail with a less-direct “received undefined” instead of clearly asserting the record exists. Consider adding an explicit expect(updatedBalance).not.toBeNull() (or similar) before asserting on tokenCredits.

    const updatedBalance = await Balance.findOne({ user: userId });
    expect(totalInput).toBeGreaterThan(premiumTokenValues['gemini-3.1'].threshold);
    expect(updatedBalance?.tokenCredits).toBeCloseTo(initialBalance - expectedTotalCost, 0);

packages/data-schemas/src/methods/spendTokens.spec.ts:1038

• Optional-chaining result?.prompt?.prompt / result?.completion?.completion makes the failure mode less explicit if spendStructuredTokens unexpectedly returns undefined/missing fields. Consider asserting result (and the nested objects) are defined before the numeric comparisons so the test pinpoints whether the issue is “no result returned” vs “wrong math”.

      expect(result?.prompt?.prompt).toBeCloseTo(-expectedPromptCost, 0);
      expect(result?.completion?.completion).toBeCloseTo(-expectedCompletionCost, 0);

api/server/middleware/canDeleteAccount.js:22

• hasCapability is awaited even when ALLOW_ACCOUNT_DELETION is enabled. That introduces an unnecessary DB call and can cause account deletion to fail if the capability check throws, despite deletion being allowed by config. Consider short-circuiting on isEnabled(ALLOW_ACCOUNT_DELETION) first (and/or wrapping the capability check in a try/catch).

  const { ALLOW_ACCOUNT_DELETION = true } = process.env;
  const hasManageUsers = user ? await hasCapability(user, SystemCapabilities.MANAGE_USERS) : false;
  if (hasManageUsers || isEnabled(ALLOW_ACCOUNT_DELETION)) {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 35 out of 35 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

packages/api/src/middleware/capabilities.ts:86

• hasConfigCapability calls hasCapability twice (broad + section fallback), which resolves principals twice via getUserPrincipals. This adds an extra DB/group lookup on every fallback check. Consider resolving principals once inside hasConfigCapability and calling hasCapabilityForPrincipals directly for both capability checks to avoid duplicate work.

  async function hasConfigCapability(
    user: CapabilityUser,
    section: ConfigSection,
    verb: 'manage' | 'read' = 'manage',
  ): Promise<boolean> {
    const broadCap =
      verb === 'manage' ? SystemCapabilities.MANAGE_CONFIGS : SystemCapabilities.READ_CONFIGS;
    if (await hasCapability(user, broadCap)) {
      return true;
    }
    const sectionCap =
      verb === 'manage' ? configCapability(section) : readConfigCapability(section);
    return hasCapability(user, sectionCap);
  }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.