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

64.9 KB
Raw Blame
import mongoose, { Types } from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { PrincipalType, SystemRoles } from 'librechat-data-provider';
import type { SystemCapability } from '~/types/admin';
import type * as t from '~/types';
import { SystemCapabilities, CapabilityImplications } from '~/admin/capabilities';
import { createSystemGrantMethods } from './systemGrant';
import systemGrantSchema from '~/schema/systemGrant';
import logger from '~/config/winston';

jest.mock('~/config/winston', () => ({
  error: jest.fn(),
  warn: jest.fn(),
  info: jest.fn(),
  debug: jest.fn(),
}));

let mongoServer: MongoMemoryServer;
let SystemGrant: mongoose.Model<t.ISystemGrant>;
let methods: ReturnType<typeof createSystemGrantMethods>;

beforeAll(async () => {
  mongoServer = await MongoMemoryServer.create();
  SystemGrant =
    mongoose.models.SystemGrant || mongoose.model<t.ISystemGrant>('SystemGrant', systemGrantSchema);
  methods = createSystemGrantMethods(mongoose);
  await mongoose.connect(mongoServer.getUri());
  // Connecting does not wait for the unique index. Complete initialization
  // before any seeding or duplicate writes can race the background build.
  await SystemGrant.init();
});

afterAll(async () => {
  await mongoose.disconnect();
  await mongoServer.stop();
});

beforeEach(async () => {
  await SystemGrant.deleteMany({});
});

describe('systemGrant methods', () => {
  describe('seedSystemGrants', () => {
    it('seeds every SystemCapabilities value for the ADMIN role', async () => {
      await methods.seedSystemGrants();

      const grants = await SystemGrant.find({
        principalType: PrincipalType.ROLE,
        principalId: SystemRoles.ADMIN,
      }).lean();

      const expected = Object.values(SystemCapabilities).sort();
      const actual = grants.map((g) => g.capability).sort();
      expect(actual).toEqual(expected);
    });

    it('is idempotent — duplicate calls produce no extra documents', async () => {
      await methods.seedSystemGrants();
      await methods.seedSystemGrants();
      await methods.seedSystemGrants();

      const count = await SystemGrant.countDocuments({
        principalType: PrincipalType.ROLE,
        principalId: SystemRoles.ADMIN,
      });
      expect(count).toBe(Object.values(SystemCapabilities).length);
    });

    it('seeds platform-level grants (no tenantId field)', async () => {
      await methods.seedSystemGrants();

      const withTenant = await SystemGrant.countDocuments({
        principalType: PrincipalType.ROLE,
        principalId: SystemRoles.ADMIN,
        tenantId: { $exists: true },
      });
      expect(withTenant).toBe(0);
    });

    it('does not throw when called (try-catch protects startup)', async () => {
      await expect(methods.seedSystemGrants()).resolves.not.toThrow();
    });

    it('retries on transient failure and succeeds', async () => {
      jest.useFakeTimers();
      jest.spyOn(SystemGrant, 'bulkWrite').mockRejectedValueOnce(new Error('disk full'));

      const seedPromise = methods.seedSystemGrants();
      await jest.advanceTimersByTimeAsync(5000);
      await seedPromise;

      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('Attempt 1/3 failed'));
      jest.useRealTimers();
    });

    it('logs error after all retries exhausted', async () => {
      jest.useFakeTimers();
      jest
        .spyOn(SystemGrant, 'bulkWrite')
        .mockRejectedValueOnce(new Error('disk full'))
        .mockRejectedValueOnce(new Error('disk full'))
        .mockRejectedValueOnce(new Error('disk full'));

      const seedPromise = methods.seedSystemGrants();
      await jest.advanceTimersByTimeAsync(10000);
      await seedPromise;

      expect(logger.error).toHaveBeenCalledWith(
        expect.stringContaining('Failed to seed capabilities after all retries'),
        expect.any(Error),
      );
      jest.useRealTimers();
    });
  });

  describe('grantCapability', () => {
    it('creates a grant and returns the document', async () => {
      const userId = new Types.ObjectId();
      const { grant: doc, created } = await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });

      expect(doc).toBeTruthy();
      expect(created).toBe(true);
      expect(doc!.principalType).toBe(PrincipalType.USER);
      expect(doc!.capability).toBe(SystemCapabilities.READ_USERS);
      expect(doc!.grantedAt).toBeInstanceOf(Date);
    });

    it('is idempotent — second call does not create a duplicate', async () => {
      const userId = new Types.ObjectId();
      const params = {
        principalType: PrincipalType.USER as const,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS as SystemCapability,
      };

      await methods.grantCapability(params);
      await methods.grantCapability(params);

      const count = await SystemGrant.countDocuments({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });
      expect(count).toBe(1);
    });

    it('stores grantedBy when provided', async () => {
      const userId = new Types.ObjectId();
      const grantedBy = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_CONFIGS,
        grantedBy,
      });

      const grant = await SystemGrant.findOne({
        principalType: PrincipalType.USER,
        principalId: userId,
      }).lean();

      expect(grant!.grantedBy!.toString()).toBe(grantedBy.toString());
    });

    it('stores tenant-scoped grants with tenantId field present', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USAGE,
        tenantId: 'tenant-abc',
      });

      const grant = await SystemGrant.findOne({
        principalType: PrincipalType.USER,
        principalId: userId,
        tenantId: 'tenant-abc',
      }).lean();

      expect(grant).toBeTruthy();
      expect(grant!.tenantId).toBe('tenant-abc');
    });

    it('normalizes string userId to ObjectId for USER principal', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId.toString(),
        capability: SystemCapabilities.READ_USERS,
      });

      const grant = await SystemGrant.findOne({ capability: SystemCapabilities.READ_USERS }).lean();
      expect(grant!.principalId.toString()).toBe(userId.toString());
      expect(grant!.principalId).toBeInstanceOf(Types.ObjectId);
    });

    it('normalizes string groupId to ObjectId for GROUP principal', async () => {
      const groupId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: groupId.toString(),
        capability: SystemCapabilities.READ_AGENTS,
      });

      const grant = await SystemGrant.findOne({
        capability: SystemCapabilities.READ_AGENTS,
      }).lean();
      expect(grant!.principalId).toBeInstanceOf(Types.ObjectId);
    });

    it('keeps ROLE principalId as a string (no ObjectId cast)', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'CUSTOM_ROLE',
        capability: SystemCapabilities.READ_CONFIGS,
      });

      const grant = await SystemGrant.findOne({
        principalType: PrincipalType.ROLE,
        principalId: 'CUSTOM_ROLE',
      }).lean();

      expect(grant).toBeTruthy();
      expect(typeof grant!.principalId).toBe('string');
    });

    it('allows same capability for same principal in different tenants', async () => {
      const userId = new Types.ObjectId();
      const params = {
        principalType: PrincipalType.USER as const,
        principalId: userId,
        capability: SystemCapabilities.ACCESS_ADMIN as SystemCapability,
      };

      await methods.grantCapability({ ...params, tenantId: 'tenant-1' });
      await methods.grantCapability({ ...params, tenantId: 'tenant-2' });

      const count = await SystemGrant.countDocuments({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      expect(count).toBe(2);
    });

    it('handles E11000 race condition — returns existing doc instead of throwing', async () => {
      const userId = new Types.ObjectId();
      const params = {
        principalType: PrincipalType.USER as const,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS as SystemCapability,
      };

      const { grant: original } = await methods.grantCapability(params);

      // Simulate a race: findOneAndUpdate upserts but hits a duplicate key
      const model = mongoose.models.SystemGrant;
      jest
        .spyOn(model, 'findOneAndUpdate')
        .mockRejectedValueOnce(
          Object.assign(new Error('E11000 duplicate key error'), { code: 11000 }),
        );

      const { grant: result, created } = await methods.grantCapability(params);
      expect(result).toBeTruthy();
      // a lost upsert race is not a new creation, so it must not be audited
      expect(created).toBe(false);
      expect(result!.capability).toBe(SystemCapabilities.READ_USERS);
      expect(result!.principalId.toString()).toBe(original!.principalId.toString());
    });

    it('re-throws non-E11000 errors from findOneAndUpdate', async () => {
      const model = mongoose.models.SystemGrant;
      jest.spyOn(model, 'findOneAndUpdate').mockRejectedValueOnce(new Error('connection timeout'));

      await expect(
        methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: new Types.ObjectId(),
          capability: SystemCapabilities.READ_USERS,
        }),
      ).rejects.toThrow('connection timeout');
    });

    it('throws TypeError for invalid ObjectId string on USER principal', async () => {
      await expect(
        methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: 'not-a-valid-objectid',
          capability: SystemCapabilities.READ_USERS,
        }),
      ).rejects.toThrow(TypeError);
    });

    it('throws TypeError for invalid ObjectId string on GROUP principal', async () => {
      await expect(
        methods.grantCapability({
          principalType: PrincipalType.GROUP,
          principalId: 'also-invalid',
          capability: SystemCapabilities.READ_AGENTS,
        }),
      ).rejects.toThrow(TypeError);
    });

    it('accepts any string for ROLE principal without ObjectId validation', async () => {
      const { grant: doc } = await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'ANY_STRING_HERE',
        capability: SystemCapabilities.READ_CONFIGS,
      });
      expect(doc).toBeTruthy();
      expect(doc!.principalId).toBe('ANY_STRING_HERE');
    });
  });

  describe('revokeCapability', () => {
    it('removes the grant document', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });

      await methods.revokeCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });

      const grant = await SystemGrant.findOne({
        principalType: PrincipalType.USER,
        principalId: userId,
      }).lean();
      expect(grant).toBeNull();
    });

    it('is a no-op when the grant does not exist', async () => {
      await expect(
        methods.revokeCapability({
          principalType: PrincipalType.USER,
          principalId: new Types.ObjectId(),
          capability: SystemCapabilities.MANAGE_USERS,
        }),
      ).resolves.not.toThrow();
    });

    it('normalizes string userId when revoking', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USAGE,
      });

      await methods.revokeCapability({
        principalType: PrincipalType.USER,
        principalId: userId.toString(),
        capability: SystemCapabilities.READ_USAGE,
      });

      const count = await SystemGrant.countDocuments({
        principalType: PrincipalType.USER,
        principalId: userId,
      });
      expect(count).toBe(0);
    });

    it('only revokes the specified tenant grant', async () => {
      const userId = new Types.ObjectId();
      const params = {
        principalType: PrincipalType.USER as const,
        principalId: userId,
        capability: SystemCapabilities.READ_CONFIGS as SystemCapability,
      };

      await methods.grantCapability({ ...params, tenantId: 'tenant-1' });
      await methods.grantCapability({ ...params, tenantId: 'tenant-2' });

      await methods.revokeCapability({ ...params, tenantId: 'tenant-1' });

      const remaining = await SystemGrant.find({
        principalType: PrincipalType.USER,
        principalId: userId,
      }).lean();

      expect(remaining).toHaveLength(1);
      expect(remaining[0].tenantId).toBe('tenant-2');
    });

    it('throws TypeError for invalid ObjectId string on USER principal', async () => {
      await expect(
        methods.revokeCapability({
          principalType: PrincipalType.USER,
          principalId: 'bad-id',
          capability: SystemCapabilities.READ_USERS,
        }),
      ).rejects.toThrow(TypeError);
    });
  });

  describe('hasCapabilityForPrincipals', () => {
    it('returns true when a role principal holds the capability', async () => {
      await methods.seedSystemGrants();

      const result = await methods.hasCapabilityForPrincipals({
        principals: [
          { principalType: PrincipalType.USER, principalId: new Types.ObjectId() },
          { principalType: PrincipalType.ROLE, principalId: SystemRoles.ADMIN },
          { principalType: PrincipalType.PUBLIC },
        ],
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      expect(result).toBe(true);
    });

    it('returns false when no principal has the capability', async () => {
      const result = await methods.hasCapabilityForPrincipals({
        principals: [
          { principalType: PrincipalType.USER, principalId: new Types.ObjectId() },
          { principalType: PrincipalType.ROLE, principalId: SystemRoles.USER },
          { principalType: PrincipalType.PUBLIC },
        ],
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      expect(result).toBe(false);
    });

    it('returns false for an empty principals array', async () => {
      const result = await methods.hasCapabilityForPrincipals({
        principals: [],
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      expect(result).toBe(false);
    });

    it('returns false when only PUBLIC principals are present', async () => {
      const result = await methods.hasCapabilityForPrincipals({
        principals: [{ principalType: PrincipalType.PUBLIC }],
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      expect(result).toBe(false);
    });

    it('matches user-level grants', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_CONFIGS,
      });

      const result = await methods.hasCapabilityForPrincipals({
        principals: [
          { principalType: PrincipalType.USER, principalId: userId },
          { principalType: PrincipalType.ROLE, principalId: SystemRoles.USER },
        ],
        capability: SystemCapabilities.READ_CONFIGS,
      });
      expect(result).toBe(true);
    });

    it('matches group-level grants', async () => {
      const groupId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: groupId,
        capability: SystemCapabilities.READ_USAGE,
      });

      const result = await methods.hasCapabilityForPrincipals({
        principals: [
          { principalType: PrincipalType.USER, principalId: new Types.ObjectId() },
          { principalType: PrincipalType.GROUP, principalId: groupId },
        ],
        capability: SystemCapabilities.READ_USAGE,
      });
      expect(result).toBe(true);
    });

    it('finds grant when string userId was used to create it and ObjectId to query', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId.toString(),
        capability: SystemCapabilities.READ_USAGE,
      });

      const result = await methods.hasCapabilityForPrincipals({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
        capability: SystemCapabilities.READ_USAGE,
      });
      expect(result).toBe(true);
    });

    describe('capability implications', () => {
      it.each(
        (
          Object.entries(CapabilityImplications) as [SystemCapability, SystemCapability[]][]
        ).flatMap(([broad, implied]) => implied.map((imp) => [broad, imp] as const)),
      )('%s implies %s', async (broadCap, impliedCap) => {
        const userId = new Types.ObjectId();

        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: broadCap,
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: impliedCap,
        });
        expect(result).toBe(true);
      });

      it.each(
        (
          Object.entries(CapabilityImplications) as [SystemCapability, SystemCapability[]][]
        ).flatMap(([broad, implied]) => implied.map((imp) => [imp, broad] as const)),
      )('%s does NOT imply %s (reverse)', async (narrowCap, broadCap) => {
        const userId = new Types.ObjectId();

        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: narrowCap,
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: broadCap,
        });
        expect(result).toBe(false);
      });
    });

    describe('hierarchical config capabilities', () => {
      it('manage:configs satisfies manage:configs:<section>', async () => {
        const userId = new Types.ObjectId();
        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.MANAGE_CONFIGS,
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: 'manage:configs:endpoints' as SystemCapability,
        });
        expect(result).toBe(true);
      });

      it('manage:configs satisfies read:configs:<section> transitively', async () => {
        const userId = new Types.ObjectId();
        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.MANAGE_CONFIGS,
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: 'read:configs:endpoints' as SystemCapability,
        });
        expect(result).toBe(true);
      });

      it('read:configs satisfies read:configs:<section> but NOT manage:configs:<section>', async () => {
        const userId = new Types.ObjectId();
        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.READ_CONFIGS,
        });

        const readResult = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: 'read:configs:endpoints' as SystemCapability,
        });
        expect(readResult).toBe(true);

        const manageResult = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: 'manage:configs:endpoints' as SystemCapability,
        });
        expect(manageResult).toBe(false);
      });

      it('assign:configs satisfies assign:configs:<target>', async () => {
        const userId = new Types.ObjectId();
        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.ASSIGN_CONFIGS,
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: 'assign:configs:user' as SystemCapability,
        });
        expect(result).toBe(true);
      });
    });

    describe('tenant scoping', () => {
      it('tenant-scoped grant does not match platform-level query', async () => {
        const userId = new Types.ObjectId();

        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.READ_CONFIGS,
          tenantId: 'tenant-1',
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: SystemCapabilities.READ_CONFIGS,
        });
        expect(result).toBe(false);
      });

      it('platform-level grant satisfies tenant-scoped query', async () => {
        const userId = new Types.ObjectId();

        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.READ_CONFIGS,
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: SystemCapabilities.READ_CONFIGS,
          tenantId: 'tenant-1',
        });
        expect(result).toBe(true);
      });

      it('tenant-scoped grant matches same-tenant query', async () => {
        const userId = new Types.ObjectId();

        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.READ_CONFIGS,
          tenantId: 'tenant-1',
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: SystemCapabilities.READ_CONFIGS,
          tenantId: 'tenant-1',
        });
        expect(result).toBe(true);
      });

      it('tenant-scoped grant does not match different tenant', async () => {
        const userId = new Types.ObjectId();

        await methods.grantCapability({
          principalType: PrincipalType.USER,
          principalId: userId,
          capability: SystemCapabilities.READ_CONFIGS,
          tenantId: 'tenant-1',
        });

        const result = await methods.hasCapabilityForPrincipals({
          principals: [{ principalType: PrincipalType.USER, principalId: userId }],
          capability: SystemCapabilities.READ_CONFIGS,
          tenantId: 'tenant-2',
        });
        expect(result).toBe(false);
      });
    });
  });

  describe('getCapabilitiesForPrincipal', () => {
    it('lists all capabilities for the ADMIN role after seeding', async () => {
      await methods.seedSystemGrants();

      const grants = await methods.getCapabilitiesForPrincipal({
        principalType: PrincipalType.ROLE,
        principalId: SystemRoles.ADMIN,
      });

      expect(grants).toHaveLength(Object.values(SystemCapabilities).length);
      const caps = grants.map((g) => g.capability).sort();
      expect(caps).toEqual(Object.values(SystemCapabilities).sort());
    });

    it('returns empty array when principal has no grants', async () => {
      const grants = await methods.getCapabilitiesForPrincipal({
        principalType: PrincipalType.ROLE,
        principalId: SystemRoles.USER,
      });
      expect(grants).toHaveLength(0);
    });

    it('normalizes string userId for lookup', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USAGE,
      });

      const grants = await methods.getCapabilitiesForPrincipal({
        principalType: PrincipalType.USER,
        principalId: userId.toString(),
      });
      expect(grants).toHaveLength(1);
      expect(grants[0].capability).toBe(SystemCapabilities.READ_USAGE);
    });

    it('only returns grants for the specified tenant', async () => {
      const userId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_CONFIGS,
        tenantId: 'tenant-1',
      });
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USAGE,
        tenantId: 'tenant-2',
      });

      const grants = await methods.getCapabilitiesForPrincipal({
        principalType: PrincipalType.USER,
        principalId: userId,
        tenantId: 'tenant-1',
      });
      expect(grants).toHaveLength(1);
      expect(grants[0].capability).toBe(SystemCapabilities.READ_CONFIGS);
    });

    it('includes platform-level grants when called with a tenantId', async () => {
      await methods.seedSystemGrants();

      const grants = await methods.getCapabilitiesForPrincipal({
        principalType: PrincipalType.ROLE,
        principalId: SystemRoles.ADMIN,
        tenantId: 'acme',
      });

      expect(grants.some((g) => g.capability === SystemCapabilities.ACCESS_ADMIN)).toBe(true);
      expect(grants).toHaveLength(Object.values(SystemCapabilities).length);
    });

    it('throws TypeError for invalid ObjectId string on USER principal', async () => {
      await expect(
        methods.getCapabilitiesForPrincipal({
          principalType: PrincipalType.USER,
          principalId: 'not-valid',
        }),
      ).rejects.toThrow(TypeError);
    });
  });

  describe('findGrantsForPrincipal', () => {
    it('reads the grants deleteGrantsForPrincipal would remove, without removing them', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'find-role',
        capability: SystemCapabilities.READ_USERS,
      });

      const found = await methods.findGrantsForPrincipal(PrincipalType.ROLE, 'find-role');
      expect(found.map((g) => g.capability)).toEqual([SystemCapabilities.READ_USERS]);
      expect(await methods.findGrantsForPrincipal(PrincipalType.ROLE, 'find-role')).toHaveLength(1);
    });
  });

  describe('moveGrantsToPrincipal', () => {
    const grant = (principalId: string, capability: SystemCapability, tenantId?: string) =>
      methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId,
        capability,
        tenantId,
      });

    const held = async (principalId: string) =>
      (
        await SystemGrant.find({ principalType: PrincipalType.ROLE, principalId })
          .sort({ capability: 1, tenantId: 1 })
          .lean()
      ).map((g) => `${g.tenantId ?? '-'}:${g.capability}`);

    it('re-keys every grant to the new name, keeping identity and history', async () => {
      const { grant: readUsers } = await grant('editor', SystemCapabilities.READ_USERS);
      await grant('editor', SystemCapabilities.READ_CONFIGS);

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');

      expect(move.moved.map((g) => g.capability).sort()).toEqual(
        [SystemCapabilities.READ_CONFIGS, SystemCapabilities.READ_USERS].sort(),
      );
      expect(move.superseded).toEqual([]);
      expect(await held('editor')).toEqual([]);
      expect(await held('writer')).toEqual(
        [`-:${SystemCapabilities.READ_CONFIGS}`, `-:${SystemCapabilities.READ_USERS}`].sort(),
      );
      const after = await SystemGrant.findById(readUsers?._id).lean();
      expect(after?.principalId).toBe('writer');
      expect(after?.grantedAt).toEqual(readUsers?.grantedAt);
    });

    it('moves only the caller tenant grants when a tenant is given, like the delete cascade', async () => {
      await grant('editor', SystemCapabilities.READ_USERS, 'tenant-a');
      await grant('editor', SystemCapabilities.READ_USERS, 'tenant-b');
      await grant('editor', SystemCapabilities.READ_CONFIGS);

      await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer', {
        tenantId: 'tenant-a',
      });

      expect(await held('writer')).toEqual([`tenant-a:${SystemCapabilities.READ_USERS}`]);
      expect(await held('editor')).toEqual(
        [
          `-:${SystemCapabilities.READ_CONFIGS}`,
          `tenant-b:${SystemCapabilities.READ_USERS}`,
        ].sort(),
      );
    });

    it('moves only platform-level grants when no tenant is given, as the delete cascade removes them', async () => {
      await grant('editor', SystemCapabilities.READ_USERS, 'tenant-a');
      await grant('editor', SystemCapabilities.READ_CONFIGS);
      await grant('writer', SystemCapabilities.READ_USERS, 'tenant-a');

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');

      expect(move.moved.map((g) => g.capability)).toEqual([SystemCapabilities.READ_CONFIGS]);
      expect(await held('editor')).toEqual([`tenant-a:${SystemCapabilities.READ_USERS}`]);
      expect(await held('writer')).toEqual(
        [
          `-:${SystemCapabilities.READ_CONFIGS}`,
          `tenant-a:${SystemCapabilities.READ_USERS}`,
        ].sort(),
      );
    });

    it('drops a grant the new name already holds instead of colliding on the unique index', async () => {
      await grant('editor', SystemCapabilities.READ_USERS);
      await grant('editor', SystemCapabilities.READ_CONFIGS);
      await grant('writer', SystemCapabilities.READ_USERS);

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');

      expect(move.moved.map((g) => g.capability)).toEqual([SystemCapabilities.READ_CONFIGS]);
      expect(move.superseded.map((g) => g.capability)).toEqual([SystemCapabilities.READ_USERS]);
      expect(await held('editor')).toEqual([]);
      expect(await held('writer')).toEqual(
        [`-:${SystemCapabilities.READ_CONFIGS}`, `-:${SystemCapabilities.READ_USERS}`].sort(),
      );
    });

    it('returns nothing and writes nothing for a principal without grants', async () => {
      await grant('writer', SystemCapabilities.READ_USERS);

      expect(await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'none', 'writer')).toEqual({
        moved: [],
        superseded: [],
      });
      expect(await held('writer')).toEqual([`-:${SystemCapabilities.READ_USERS}`]);
    });

    it('restores the source exactly, leaving grants the target held before untouched', async () => {
      const { grant: readUsers } = await grant('editor', SystemCapabilities.READ_USERS);
      const { grant: readConfigs } = await grant('editor', SystemCapabilities.READ_CONFIGS);
      await grant('writer', SystemCapabilities.READ_USERS);

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');
      await methods.restoreMovedGrants(PrincipalType.ROLE, 'editor', 'writer', move);

      expect(await held('editor')).toEqual(
        [`-:${SystemCapabilities.READ_CONFIGS}`, `-:${SystemCapabilities.READ_USERS}`].sort(),
      );
      expect(await held('writer')).toEqual([`-:${SystemCapabilities.READ_USERS}`]);
      const restored = await SystemGrant.find({ principalId: 'editor' }).lean();
      expect(restored.map((g) => g._id.toString()).sort()).toEqual(
        [readUsers?._id.toString(), readConfigs?._id.toString()].sort(),
      );
    });

    it('never re-creates a moved grant that was revoked before the undo', async () => {
      await grant('editor', SystemCapabilities.READ_USERS);
      await grant('editor', SystemCapabilities.READ_CONFIGS);

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');
      await methods.revokeCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'writer',
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.restoreMovedGrants(PrincipalType.ROLE, 'editor', 'writer', move);

      expect(await held('editor')).toEqual([`-:${SystemCapabilities.READ_CONFIGS}`]);
      expect(await held('writer')).toEqual([]);
    });

    it('never reports or re-creates a grant revoked between its snapshot and the move', async () => {
      await grant('editor', SystemCapabilities.READ_USERS);
      await grant('editor', SystemCapabilities.READ_CONFIGS);
      await grant('writer', SystemCapabilities.READ_USERS);
      const findOneAndDelete = SystemGrant.findOneAndDelete.bind(SystemGrant);
      /** Another admin revokes the superseded grant after the move read it, before it is removed. */
      jest.spyOn(SystemGrant, 'findOneAndDelete').mockImplementationOnce(((
        ...args: Parameters<typeof SystemGrant.findOneAndDelete>
      ) => ({
        lean: () => ({
          exec: () =>
            methods
              .revokeCapability({
                principalType: PrincipalType.ROLE,
                principalId: 'editor',
                capability: SystemCapabilities.READ_USERS,
              })
              .then(() =>
                findOneAndDelete(...args)
                  .lean()
                  .exec(),
              ),
        }),
      })) as never);

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');
      await methods.restoreMovedGrants(PrincipalType.ROLE, 'editor', 'writer', move);

      expect(move.superseded).toEqual([]);
      expect(await held('editor')).toEqual([`-:${SystemCapabilities.READ_CONFIGS}`]);
      expect(await held('writer')).toEqual([`-:${SystemCapabilities.READ_USERS}`]);
    });

    it('re-creates a superseded grant only while the new name still holds the one that superseded it', async () => {
      await grant('editor', SystemCapabilities.READ_USERS);
      await grant('editor', SystemCapabilities.READ_CONFIGS);
      await grant('writer', SystemCapabilities.READ_USERS);
      await grant('writer', SystemCapabilities.READ_CONFIGS);

      const move = await methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer');
      await methods.revokeCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'writer',
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.restoreMovedGrants(PrincipalType.ROLE, 'editor', 'writer', move);

      expect(move.superseded).toHaveLength(2);
      expect(await held('editor')).toEqual([`-:${SystemCapabilities.READ_CONFIGS}`]);
      expect(await held('writer')).toEqual([`-:${SystemCapabilities.READ_CONFIGS}`]);
    });

    it('undoes a move that fails part-way before rethrowing', async () => {
      await grant('editor', SystemCapabilities.READ_USERS);
      await grant('editor', SystemCapabilities.READ_CONFIGS);
      await grant('writer', SystemCapabilities.READ_USERS);
      const failure = new Error('write interrupted');
      const updateMany = jest.spyOn(SystemGrant, 'updateMany').mockRejectedValueOnce(failure);

      await expect(
        methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer'),
      ).rejects.toBe(failure);
      updateMany.mockRestore();

      expect(await held('editor')).toEqual(
        [`-:${SystemCapabilities.READ_CONFIGS}`, `-:${SystemCapabilities.READ_USERS}`].sort(),
      );
      expect(await held('writer')).toEqual([`-:${SystemCapabilities.READ_USERS}`]);
    });

    it('logs the grant ids, never the error text, when the undo of a failed move fails too', async () => {
      const { grant: readUsers } = await grant('editor', SystemCapabilities.READ_USERS);
      const failure = new Error('write interrupted');
      const updateMany = jest
        .spyOn(SystemGrant, 'updateMany')
        .mockRejectedValueOnce(failure)
        .mockRejectedValueOnce(new Error('undo failed near {"principalId":"editor"}'));
      (logger.error as jest.Mock).mockClear();

      await expect(
        methods.moveGrantsToPrincipal(PrincipalType.ROLE, 'editor', 'writer'),
      ).rejects.toBe(failure);
      updateMany.mockRestore();

      expect(logger.error).toHaveBeenCalledWith(
        '[moveGrantsToPrincipal] undo after a failed move failed',
        {
          principalType: PrincipalType.ROLE,
          fromPrincipalId: 'editor',
          toPrincipalId: 'writer',
          grantIds: readUsers?._id.toString(),
          errName: 'Error',
          errCode: null,
        },
      );
    });
  });

  describe('deleteGrantsForPrincipal', () => {
    it('deletes all grants for a principal', async () => {
      const groupId = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: groupId,
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: groupId,
        capability: SystemCapabilities.READ_CONFIGS,
      });

      await methods.deleteGrantsForPrincipal(PrincipalType.GROUP, groupId);

      const remaining = await SystemGrant.countDocuments({
        principalType: PrincipalType.GROUP,
        principalId: groupId,
      });
      expect(remaining).toBe(0);
    });

    it('is a no-op for principal with no grants', async () => {
      const groupId = new Types.ObjectId();

      await expect(
        methods.deleteGrantsForPrincipal(PrincipalType.GROUP, groupId),
      ).resolves.not.toThrow();
    });

    it('does not affect other principals', async () => {
      const groupA = new Types.ObjectId();
      const groupB = new Types.ObjectId();

      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: groupA,
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: groupB,
        capability: SystemCapabilities.READ_USERS,
      });

      await methods.deleteGrantsForPrincipal(PrincipalType.GROUP, groupA);

      const remainingA = await SystemGrant.countDocuments({
        principalType: PrincipalType.GROUP,
        principalId: groupA,
      });
      const remainingB = await SystemGrant.countDocuments({
        principalType: PrincipalType.GROUP,
        principalId: groupB,
      });
      expect(remainingA).toBe(0);
      expect(remainingB).toBe(1);
    });

    it('with tenantId deletes only tenant-scoped grants, not platform-level grants', async () => {
      // Platform-level grant (no tenantId)
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
        capability: SystemCapabilities.READ_USERS,
      });
      // Tenant-scoped grant
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
        capability: SystemCapabilities.READ_CONFIGS,
        tenantId: 'tenant-1',
      });
      // Different tenant grant
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
        capability: SystemCapabilities.READ_GROUPS,
        tenantId: 'tenant-2',
      });

      await methods.deleteGrantsForPrincipal(PrincipalType.ROLE, 'editor', {
        tenantId: 'tenant-1',
      });

      const remaining = await SystemGrant.find({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
      }).lean();
      const caps = remaining.map((g) => g.capability).sort();
      // Platform-level and tenant-2 grants survive
      expect(caps).toEqual([SystemCapabilities.READ_GROUPS, SystemCapabilities.READ_USERS]);
    });

    it("without tenantId deletes only platform-level grants, never a tenant's own role's", async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'temp-role',
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'temp-role',
        capability: SystemCapabilities.READ_CONFIGS,
        tenantId: 'tenant-a',
      });

      const found = await methods.findGrantsForPrincipal(PrincipalType.ROLE, 'temp-role');
      const removed = await methods.deleteGrantsForPrincipal(PrincipalType.ROLE, 'temp-role');

      expect(found.map((g) => g.capability)).toEqual([SystemCapabilities.READ_USERS]);
      expect(removed.map((g) => g.capability)).toEqual([SystemCapabilities.READ_USERS]);
      const remaining = await SystemGrant.find({
        principalType: PrincipalType.ROLE,
        principalId: 'temp-role',
      }).lean();
      expect(remaining.map((g) => [g.capability, g.tenantId])).toEqual([
        [SystemCapabilities.READ_CONFIGS, 'tenant-a'],
      ]);
    });
  });

  describe('schema validation', () => {
    it('starts with the non-sparse unique grant index ready', async () => {
      const indexes = await SystemGrant.collection.indexes();
      const unique = indexes.find((index) => index.unique === true);
      expect(unique?.key).toEqual({
        principalType: 1,
        principalId: 1,
        capability: 1,
        tenantId: 1,
      });
      expect(unique?.sparse).not.toBe(true);
    });

    it('rejects null tenantId at the schema level', async () => {
      await expect(
        SystemGrant.create({
          principalType: PrincipalType.USER,
          principalId: new Types.ObjectId(),
          capability: SystemCapabilities.READ_USERS,
          tenantId: null,
        }),
      ).rejects.toThrow(/tenantId/);
    });

    it('rejects empty string tenantId at the schema level', async () => {
      await expect(
        SystemGrant.create({
          principalType: PrincipalType.USER,
          principalId: new Types.ObjectId(),
          capability: SystemCapabilities.READ_USERS,
          tenantId: '',
        }),
      ).rejects.toThrow(/tenantId/);
    });

    it('rejects invalid principalType values', async () => {
      await expect(
        SystemGrant.create({
          principalType: 'INVALID_TYPE',
          principalId: new Types.ObjectId(),
          capability: SystemCapabilities.READ_USERS,
        }),
      ).rejects.toThrow(/principalType/);
    });

    it('requires principalType field', async () => {
      await expect(
        SystemGrant.create({
          principalId: new Types.ObjectId(),
          capability: SystemCapabilities.READ_USERS,
        }),
      ).rejects.toThrow(/principalType/);
    });

    it('requires principalId field', async () => {
      await expect(
        SystemGrant.create({
          principalType: PrincipalType.USER,
          capability: SystemCapabilities.READ_USERS,
        }),
      ).rejects.toThrow(/principalId/);
    });

    it('requires capability field', async () => {
      await expect(
        SystemGrant.create({
          principalType: PrincipalType.USER,
          principalId: new Types.ObjectId(),
        }),
      ).rejects.toThrow(/capability/);
    });

    it('rejects invalid capability strings', async () => {
      await expect(
        SystemGrant.create({
          principalType: PrincipalType.USER,
          principalId: new Types.ObjectId(),
          capability: 'god:mode',
        }),
      ).rejects.toThrow(/Invalid capability string/);
    });

    it('accepts valid section-level config capabilities', async () => {
      const doc = await SystemGrant.create({
        principalType: PrincipalType.USER,
        principalId: new Types.ObjectId(),
        capability: 'manage:configs:endpoints',
      });
      expect(doc.capability).toBe('manage:configs:endpoints');
    });

    it('accepts valid assign config capabilities', async () => {
      const doc = await SystemGrant.create({
        principalType: PrincipalType.USER,
        principalId: new Types.ObjectId(),
        capability: 'assign:configs:group',
      });
      expect(doc.capability).toBe('assign:configs:group');
    });

    it('enforces unique compound index (principalType + principalId + capability + tenantId)', async () => {
      const doc = {
        principalType: PrincipalType.USER,
        principalId: new Types.ObjectId(),
        capability: SystemCapabilities.READ_USERS,
      };

      await SystemGrant.create(doc);

      await expect(SystemGrant.create(doc)).rejects.toThrow(/duplicate key|E11000/);
    });

    it('rejects duplicate platform-level grants (absent tenantId) — non-sparse index', async () => {
      const principalId = new Types.ObjectId();

      await SystemGrant.create({
        principalType: PrincipalType.USER,
        principalId,
        capability: SystemCapabilities.ACCESS_ADMIN,
      });

      await expect(
        SystemGrant.create({
          principalType: PrincipalType.USER,
          principalId,
          capability: SystemCapabilities.ACCESS_ADMIN,
        }),
      ).rejects.toThrow(/duplicate key|E11000/);
    });

    it('allows same grant for different tenants (tenantId is part of unique key)', async () => {
      const principalId = new Types.ObjectId();
      const base = {
        principalType: PrincipalType.USER,
        principalId,
        capability: SystemCapabilities.ACCESS_ADMIN,
      };

      await SystemGrant.create({ ...base, tenantId: 'tenant-a' });
      await SystemGrant.create({ ...base, tenantId: 'tenant-b' });

      const count = await SystemGrant.countDocuments({ principalId });
      expect(count).toBe(2);
    });

    it('platform-level and tenant-scoped grants coexist (different unique key values)', async () => {
      const principalId = new Types.ObjectId();
      const base = {
        principalType: PrincipalType.USER,
        principalId,
        capability: SystemCapabilities.ACCESS_ADMIN,
      };

      await SystemGrant.create(base);
      await SystemGrant.create({ ...base, tenantId: 'tenant-1' });

      const count = await SystemGrant.countDocuments({ principalId });
      expect(count).toBe(2);
    });
  });

  describe('listGrants', () => {
    beforeEach(async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: new Types.ObjectId(),
        capability: SystemCapabilities.READ_CONFIGS,
      });
    });

    it('returns all platform-level grants when called without options', async () => {
      const grants = await methods.listGrants();
      expect(grants).toHaveLength(3);
    });

    it('respects limit parameter', async () => {
      const grants = await methods.listGrants({ limit: 2 });
      expect(grants).toHaveLength(2);
    });

    it('respects offset parameter', async () => {
      const all = await methods.listGrants();
      const page2 = await methods.listGrants({ offset: 2, limit: 10 });
      expect(page2).toHaveLength(1);
      expect(page2[0].capability).toBe(all[2].capability);
    });

    it('filters by principalTypes', async () => {
      const grants = await methods.listGrants({
        principalTypes: [PrincipalType.ROLE],
      });
      expect(grants).toHaveLength(2);
      for (const g of grants) {
        expect(g.principalType).toBe(PrincipalType.ROLE);
      }
    });

    it('returns empty array for principalTypes with no grants', async () => {
      const grants = await methods.listGrants({
        principalTypes: [PrincipalType.USER],
      });
      expect(grants).toHaveLength(0);
    });

    it('excludes tenant-scoped grants when no tenantId provided', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.MANAGE_USERS,
        tenantId: 'tenant-1',
      });

      const grants = await methods.listGrants();
      expect(grants.every((g) => !('tenantId' in g && g.tenantId))).toBe(true);
    });

    it('includes tenant and platform grants when tenantId provided', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.MANAGE_USERS,
        tenantId: 'tenant-1',
      });

      const grants = await methods.listGrants({ tenantId: 'tenant-1' });
      expect(grants).toHaveLength(4);
    });

    it('sorts by principalType then capability', async () => {
      const grants = await methods.listGrants();
      for (let i = 1; i < grants.length; i++) {
        const prev = `${grants[i - 1].principalType}:${grants[i - 1].capability}`;
        const curr = `${grants[i].principalType}:${grants[i].capability}`;
        expect(prev <= curr).toBe(true);
      }
    });
  });

  describe('countGrants', () => {
    it('returns total count matching the filter', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: new Types.ObjectId(),
        capability: SystemCapabilities.READ_CONFIGS,
      });

      const total = await methods.countGrants();
      expect(total).toBe(3);
    });

    it('filters by principalTypes', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      await methods.grantCapability({
        principalType: PrincipalType.GROUP,
        principalId: new Types.ObjectId(),
        capability: SystemCapabilities.READ_CONFIGS,
      });

      const count = await methods.countGrants({
        principalTypes: [PrincipalType.ROLE],
      });
      expect(count).toBe(1);
    });

    it('returns 0 when no grants match', async () => {
      const count = await methods.countGrants();
      expect(count).toBe(0);
    });
  });

  describe('getCapabilitiesForPrincipals', () => {
    it('returns grants across multiple principals in a single query', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'editor',
        capability: SystemCapabilities.READ_ROLES,
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [
          { principalType: PrincipalType.USER, principalId: userId },
          { principalType: PrincipalType.ROLE, principalId: 'editor' },
        ],
      });

      expect(grants).toHaveLength(2);
      const caps = grants.map((g) => g.capability).sort();
      expect(caps).toEqual([SystemCapabilities.READ_ROLES, SystemCapabilities.READ_USERS]);
    });

    it('returns empty array for empty principals list', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });

      const grants = await methods.getCapabilitiesForPrincipals({ principals: [] });
      expect(grants).toEqual([]);
    });

    it('returns only matching principals, not all grants', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'unrelated',
        capability: SystemCapabilities.MANAGE_ROLES,
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
      });

      expect(grants).toHaveLength(1);
      expect(grants[0].capability).toBe(SystemCapabilities.READ_USERS);
    });

    it('returns multiple grants for the same principal', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.MANAGE_ROLES,
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [{ principalType: PrincipalType.ROLE, principalId: 'admin' }],
      });

      expect(grants).toHaveLength(2);
    });

    it('excludes tenant-scoped grants when no tenantId provided', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.MANAGE_USERS,
        tenantId: 'tenant-1',
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [{ principalType: PrincipalType.ROLE, principalId: 'admin' }],
      });

      expect(grants).toHaveLength(1);
      expect(grants[0].capability).toBe(SystemCapabilities.ACCESS_ADMIN);
    });

    it('includes both platform and tenant grants when tenantId provided', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.MANAGE_USERS,
        tenantId: 'tenant-1',
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [{ principalType: PrincipalType.ROLE, principalId: 'admin' }],
        tenantId: 'tenant-1',
      });

      expect(grants).toHaveLength(2);
    });

    it('filters out PUBLIC principals before querying', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USERS,
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [
          { principalType: PrincipalType.PUBLIC, principalId: '' },
          { principalType: PrincipalType.USER, principalId: userId },
        ],
      });

      expect(grants).toHaveLength(1);
      expect(grants[0].capability).toBe(SystemCapabilities.READ_USERS);
    });

    it('returns empty array when all principals are PUBLIC', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.ACCESS_ADMIN,
      });

      const grants = await methods.getCapabilitiesForPrincipals({
        principals: [{ principalType: PrincipalType.PUBLIC, principalId: '' }],
      });

      expect(grants).toEqual([]);
    });
  });

  describe('getHeldCapabilities', () => {
    const userId = new Types.ObjectId();

    it('returns the subset of capabilities the principals hold', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_ROLES,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
        capabilities: [SystemCapabilities.READ_ROLES, SystemCapabilities.READ_GROUPS],
      });

      expect(held).toEqual(new Set([SystemCapabilities.READ_ROLES]));
    });

    it('returns empty set when no capabilities match', async () => {
      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: new Types.ObjectId() }],
        capabilities: [SystemCapabilities.MANAGE_ROLES],
      });

      expect(held.size).toBe(0);
    });

    it('returns empty set for empty principals', async () => {
      const held = await methods.getHeldCapabilities({
        principals: [],
        capabilities: [SystemCapabilities.READ_ROLES],
      });

      expect(held.size).toBe(0);
    });

    it('returns empty set for empty capabilities', async () => {
      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
        capabilities: [],
      });

      expect(held.size).toBe(0);
    });

    it('resolves implied capabilities via reverse implication map', async () => {
      const implUser = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: implUser,
        capability: SystemCapabilities.MANAGE_ROLES,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: implUser }],
        capabilities: [SystemCapabilities.READ_ROLES, SystemCapabilities.MANAGE_GROUPS],
      });

      expect(held).toEqual(new Set([SystemCapabilities.READ_ROLES]));
    });

    it('excludes principals with undefined principalId', async () => {
      await methods.grantCapability({
        principalType: PrincipalType.ROLE,
        principalId: 'admin',
        capability: SystemCapabilities.READ_ROLES,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.ROLE }],
        capabilities: [SystemCapabilities.READ_ROLES],
      });

      expect(held.size).toBe(0);
    });

    it('filters out PUBLIC principals', async () => {
      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.PUBLIC, principalId: '' }],
        capabilities: [SystemCapabilities.READ_ROLES],
      });

      expect(held.size).toBe(0);
    });

    it('respects tenant scoping', async () => {
      const tenantUser = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: tenantUser,
        capability: SystemCapabilities.READ_ROLES,
        tenantId: 'tenant-a',
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: tenantUser }],
        capabilities: [SystemCapabilities.READ_ROLES],
        tenantId: 'tenant-a',
      });
      expect(held).toEqual(new Set([SystemCapabilities.READ_ROLES]));

      const heldOther = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: tenantUser }],
        capabilities: [SystemCapabilities.READ_ROLES],
        tenantId: 'tenant-b',
      });
      expect(heldOther.size).toBe(0);

      const heldNoTenant = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: tenantUser }],
        capabilities: [SystemCapabilities.READ_ROLES],
      });
      expect(heldNoTenant.size).toBe(0);
    });

    it('resolves extended capability when principal holds the parent base capability', async () => {
      const extUser = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: extUser,
        capability: SystemCapabilities.MANAGE_CONFIGS,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: extUser }],
        capabilities: ['manage:configs:endpoints' as SystemCapability],
      });

      expect(held).toEqual(new Set(['manage:configs:endpoints']));
    });

    it('does not resolve extended capability when principal holds a different verb parent', async () => {
      const readOnlyUser = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: readOnlyUser,
        capability: SystemCapabilities.READ_CONFIGS,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: readOnlyUser }],
        capabilities: ['manage:configs:endpoints' as SystemCapability],
      });

      expect(held.size).toBe(0);
    });

    it('resolves a section-scoped read capability when the principal holds the same-section manage grant', async () => {
      const sectionManager = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: sectionManager,
        capability: 'manage:configs:endpoints' as SystemCapability,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: sectionManager }],
        capabilities: ['read:configs:endpoints' as SystemCapability],
      });

      expect(held).toEqual(new Set(['read:configs:endpoints']));
    });

    it("does not resolve a read capability from a different section's manage grant", async () => {
      const otherSectionManager = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: otherSectionManager,
        capability: 'manage:configs:balance' as SystemCapability,
      });

      const held = await methods.getHeldCapabilities({
        principals: [{ principalType: PrincipalType.USER, principalId: otherSectionManager }],
        capabilities: ['read:configs:endpoints' as SystemCapability],
      });

      expect(held.size).toBe(0);
    });
  });

  describe('hasAnyConfigReadAccess', () => {
    it('returns true for a broad read:configs holder', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_CONFIGS,
      });

      const result = await methods.hasAnyConfigReadAccess({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
      });
      expect(result).toBe(true);
    });

    it('returns true for a broad manage:configs holder, which implies read', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.MANAGE_CONFIGS,
      });

      const result = await methods.hasAnyConfigReadAccess({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
      });
      expect(result).toBe(true);
    });

    it('returns true for a section-scoped read:configs:<section> holder', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: 'read:configs:endpoints' as SystemCapability,
      });

      const result = await methods.hasAnyConfigReadAccess({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
      });
      expect(result).toBe(true);
    });

    it('returns true for a section-scoped manage:configs:<section> holder', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: 'manage:configs:endpoints' as SystemCapability,
      });

      const result = await methods.hasAnyConfigReadAccess({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
      });
      expect(result).toBe(true);
    });

    it('returns false for a caller with no config capability at all', async () => {
      const userId = new Types.ObjectId();
      await methods.grantCapability({
        principalType: PrincipalType.USER,
        principalId: userId,
        capability: SystemCapabilities.READ_USAGE,
      });

      const result = await methods.hasAnyConfigReadAccess({
        principals: [{ principalType: PrincipalType.USER, principalId: userId }],
      });
      expect(result).toBe(false);
    });

    it('returns false for an empty principals array', async () => {
      const result = await methods.hasAnyConfigReadAccess({ principals: [] });
      expect(result).toBe(false);
    });
  });
});