strapi-plugin-keycloak-realm-users 1.0.0

package/__tests__/services/user.test.mjs

@@ -0,0 +1,487 @@
+/**
+ * @fileoverview Unit tests for the user management service.
+ * @module __tests__/services/user
+ */
+
+import userService from '../../server/src/services/user.js';
+import {
+  createMockStrapi,
+  createMockStrapiUser,
+  createMockRealmConfig,
+  createMockKeycloakUser,
+  createMockKeycloakRole,
+} from '../mocks/strapi.mjs';
+import { AUDIT_ACTIONS, ERROR_MESSAGES, PAGINATION } from '../../server/src/constants.js';
+
+describe('User Service', () => {
+  let strapi;
+  let service;
+  let mockRealmService;
+  let mockKeycloakClient;
+  let mockPermissionService;
+  let mockAuditLogService;
+
+  beforeEach(() => {
+    mockRealmService = {
+      findOne: jest.fn().mockResolvedValue(createMockRealmConfig({ enabled: true })),
+      findOneWithSecret: jest.fn().mockResolvedValue(
+        createMockRealmConfig({ clientSecret: 'secret' })
+      ),
+    };
+
+    mockKeycloakClient = {
+      getUsers: jest.fn().mockResolvedValue([]),
+      countUsers: jest.fn().mockResolvedValue(0),
+      getUserById: jest.fn().mockResolvedValue(createMockKeycloakUser()),
+      createUser: jest.fn().mockResolvedValue({ userId: 'new-user-id' }),
+      updateUser: jest.fn().mockResolvedValue(undefined),
+      deleteUser: jest.fn().mockResolvedValue(undefined),
+      resetPassword: jest.fn().mockResolvedValue(undefined),
+      enableUser: jest.fn().mockResolvedValue(undefined),
+      disableUser: jest.fn().mockResolvedValue(undefined),
+      sendVerificationEmail: jest.fn().mockResolvedValue(undefined),
+      sendResetPasswordEmail: jest.fn().mockResolvedValue(undefined),
+      getRealmRoles: jest.fn().mockResolvedValue([]),
+      getUserRoles: jest.fn().mockResolvedValue([]),
+      assignRoles: jest.fn().mockResolvedValue(undefined),
+      removeRoles: jest.fn().mockResolvedValue(undefined),
+    };
+
+    mockPermissionService = {
+      canAccessRealm: jest.fn().mockResolvedValue(true),
+    };
+
+    mockAuditLogService = {
+      log: jest.fn().mockResolvedValue(undefined),
+    };
+
+    strapi = createMockStrapi({
+      pluginServices: {
+        realm: mockRealmService,
+        'keycloak-client': mockKeycloakClient,
+        permission: mockPermissionService,
+        'audit-log': mockAuditLogService,
+      },
+    });
+    service = userService({ strapi });
+  });
+
+  describe('getRealmWithPermission', () => {
+    it('should return realm when user has permission', async () => {
+      const user = createMockStrapiUser();
+
+      const result = await service.getRealmWithPermission('realm-123', user, 'canRead');
+
+      expect(result.clientSecret).toBe('secret');
+      expect(mockRealmService.findOne).toHaveBeenCalledWith('realm-123');
+      expect(mockPermissionService.canAccessRealm).toHaveBeenCalledWith(user, 'realm-123', 'canRead');
+    });
+
+    it('should throw when realm is disabled', async () => {
+      mockRealmService.findOne.mockResolvedValue(createMockRealmConfig({ enabled: false }));
+      const user = createMockStrapiUser();
+
+      await expect(
+        service.getRealmWithPermission('realm-123', user, 'canRead')
+      ).rejects.toThrow();
+
+      try {
+        await service.getRealmWithPermission('realm-123', user, 'canRead');
+      } catch (err) {
+        expect(err.sanitizedMessage).toBe(ERROR_MESSAGES.REALM_DISABLED);
+      }
+    });
+
+    it('should throw when user lacks permission', async () => {
+      mockPermissionService.canAccessRealm.mockResolvedValue(false);
+      const user = createMockStrapiUser();
+
+      try {
+        await service.getRealmWithPermission('realm-123', user, 'canDelete');
+      } catch (err) {
+        expect(err.sanitizedMessage).toBe(ERROR_MESSAGES.REALM_ACCESS_DENIED);
+      }
+    });
+  });
+
+  describe('listUsers', () => {
+    it('should return paginated users', async () => {
+      const users = [createMockKeycloakUser(), createMockKeycloakUser({ id: 'user-2' })];
+      mockKeycloakClient.getUsers.mockResolvedValue(users);
+      mockKeycloakClient.countUsers.mockResolvedValue(50);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.listUsers('realm-123', { page: 2, pageSize: 10 }, strapiUser);
+
+      expect(result.users).toEqual(users);
+      expect(result.pagination).toEqual({
+        page: 2,
+        pageSize: 10,
+        total: 50,
+        pageCount: 5,
+      });
+      expect(mockKeycloakClient.getUsers).toHaveBeenCalledWith(
+        expect.anything(),
+        { search: '', first: 10, max: 10 }
+      );
+    });
+
+    it('should use default pagination', async () => {
+      const strapiUser = createMockStrapiUser();
+
+      await service.listUsers('realm-123', {}, strapiUser);
+
+      expect(mockKeycloakClient.getUsers).toHaveBeenCalledWith(
+        expect.anything(),
+        { search: '', first: 0, max: PAGINATION.PAGE_SIZE }
+      );
+    });
+
+    it('should pass search parameter', async () => {
+      const strapiUser = createMockStrapiUser();
+
+      await service.listUsers('realm-123', { search: 'john' }, strapiUser);
+
+      expect(mockKeycloakClient.getUsers).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ search: 'john' })
+      );
+      expect(mockKeycloakClient.countUsers).toHaveBeenCalledWith(
+        expect.anything(),
+        { search: 'john' }
+      );
+    });
+  });
+
+  describe('getUser', () => {
+    it('should return user by ID', async () => {
+      const kcUser = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(kcUser);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.getUser('realm-123', 'kc-user-123', strapiUser);
+
+      expect(result).toEqual(kcUser);
+      expect(mockKeycloakClient.getUserById).toHaveBeenCalledWith(
+        expect.anything(),
+        'kc-user-123'
+      );
+    });
+  });
+
+  describe('createUser', () => {
+    it('should create user and log action', async () => {
+      const newUser = createMockKeycloakUser({ id: 'new-user-id' });
+      mockKeycloakClient.getUserById.mockResolvedValue(newUser);
+      const strapiUser = createMockStrapiUser();
+      const userData = {
+        username: 'newuser',
+        email: 'new@example.com',
+        firstName: 'New',
+        lastName: 'User',
+      };
+
+      const result = await service.createUser('realm-123', userData, strapiUser);
+
+      expect(result).toEqual(newUser);
+      expect(mockKeycloakClient.createUser).toHaveBeenCalledWith(expect.anything(), userData);
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.CREATE_USER,
+          keycloakUsername: 'newuser',
+          details: expect.objectContaining({ email: 'new@example.com' }),
+        })
+      );
+    });
+
+    it('should require canCreate permission', async () => {
+      mockPermissionService.canAccessRealm.mockResolvedValue(false);
+      const strapiUser = createMockStrapiUser();
+
+      await expect(
+        service.createUser('realm-123', { username: 'test' }, strapiUser)
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('updateUser', () => {
+    it('should update user and log action', async () => {
+      const existingUser = createMockKeycloakUser();
+      const updatedUser = createMockKeycloakUser({ firstName: 'Updated' });
+      mockKeycloakClient.getUserById
+        .mockResolvedValueOnce(existingUser)
+        .mockResolvedValueOnce(updatedUser);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.updateUser(
+        'realm-123',
+        'kc-user-123',
+        { firstName: 'Updated' },
+        strapiUser
+      );
+
+      expect(result).toEqual(updatedUser);
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.UPDATE_USER,
+          details: { changes: { firstName: 'Updated' } },
+        })
+      );
+    });
+  });
+
+  describe('deleteUser', () => {
+    it('should delete user and log action', async () => {
+      const user = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.deleteUser('realm-123', 'kc-user-123', strapiUser);
+
+      expect(result).toEqual({ success: true });
+      expect(mockKeycloakClient.deleteUser).toHaveBeenCalledWith(expect.anything(), 'kc-user-123');
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.DELETE_USER,
+          keycloakUserId: 'kc-user-123',
+        })
+      );
+    });
+  });
+
+  describe('resetPassword', () => {
+    it('should reset password and log action', async () => {
+      const user = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.resetPassword(
+        'realm-123',
+        'kc-user-123',
+        'NewPass123!',
+        true,
+        strapiUser
+      );
+
+      expect(result).toEqual({ success: true });
+      expect(mockKeycloakClient.resetPassword).toHaveBeenCalledWith(
+        expect.anything(),
+        'kc-user-123',
+        'NewPass123!',
+        true
+      );
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.RESET_PASSWORD,
+          details: { temporary: true },
+        })
+      );
+    });
+
+    it('should require canResetPassword permission', async () => {
+      mockPermissionService.canAccessRealm.mockResolvedValue(false);
+      const strapiUser = createMockStrapiUser();
+
+      await expect(
+        service.resetPassword('realm-123', 'kc-user-123', 'pass', false, strapiUser)
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('enableUser / disableUser', () => {
+    it('should enable user and log action', async () => {
+      const user = createMockKeycloakUser({ enabled: false });
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const strapiUser = createMockStrapiUser();
+
+      await service.enableUser('realm-123', 'kc-user-123', strapiUser);
+
+      expect(mockKeycloakClient.enableUser).toHaveBeenCalled();
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({ action: AUDIT_ACTIONS.ENABLE_USER })
+      );
+    });
+
+    it('should disable user and log action', async () => {
+      const user = createMockKeycloakUser({ enabled: true });
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const strapiUser = createMockStrapiUser();
+
+      await service.disableUser('realm-123', 'kc-user-123', strapiUser);
+
+      expect(mockKeycloakClient.disableUser).toHaveBeenCalled();
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({ action: AUDIT_ACTIONS.DISABLE_USER })
+      );
+    });
+  });
+
+  describe('sendVerificationEmail', () => {
+    it('should send verification email and log action', async () => {
+      const user = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const strapiUser = createMockStrapiUser();
+
+      await service.sendVerificationEmail('realm-123', 'kc-user-123', strapiUser);
+
+      expect(mockKeycloakClient.sendVerificationEmail).toHaveBeenCalled();
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({ action: AUDIT_ACTIONS.SEND_VERIFY_EMAIL })
+      );
+    });
+  });
+
+  describe('sendResetPasswordEmail', () => {
+    it('should send password reset email and log action', async () => {
+      const user = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const strapiUser = createMockStrapiUser();
+
+      await service.sendResetPasswordEmail('realm-123', 'kc-user-123', strapiUser);
+
+      expect(mockKeycloakClient.sendResetPasswordEmail).toHaveBeenCalled();
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({ action: AUDIT_ACTIONS.SEND_RESET_PASSWORD_EMAIL })
+      );
+    });
+
+    it('should require canResetPassword permission', async () => {
+      mockPermissionService.canAccessRealm.mockResolvedValue(false);
+      const strapiUser = createMockStrapiUser();
+
+      await expect(
+        service.sendResetPasswordEmail('realm-123', 'kc-user-123', strapiUser)
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('getRoles / getUserRoles', () => {
+    it('should get all realm roles', async () => {
+      const roles = [createMockKeycloakRole({ name: 'admin' })];
+      mockKeycloakClient.getRealmRoles.mockResolvedValue(roles);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.getRoles('realm-123', strapiUser);
+
+      expect(result).toEqual(roles);
+    });
+
+    it('should get user roles', async () => {
+      const roles = [createMockKeycloakRole({ name: 'user' })];
+      mockKeycloakClient.getUserRoles.mockResolvedValue(roles);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.getUserRoles('realm-123', 'kc-user-123', strapiUser);
+
+      expect(result).toEqual(roles);
+    });
+  });
+
+  describe('assignRoles / removeRoles', () => {
+    it('should assign roles and log action', async () => {
+      const user = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const roles = [createMockKeycloakRole({ name: 'admin' })];
+      const strapiUser = createMockStrapiUser();
+
+      await service.assignRoles('realm-123', 'kc-user-123', roles, strapiUser);
+
+      expect(mockKeycloakClient.assignRoles).toHaveBeenCalledWith(
+        expect.anything(),
+        'kc-user-123',
+        roles
+      );
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.ASSIGN_ROLE,
+          details: { roles: ['admin'] },
+        })
+      );
+    });
+
+    it('should remove roles and log action', async () => {
+      const user = createMockKeycloakUser();
+      mockKeycloakClient.getUserById.mockResolvedValue(user);
+      const roles = [createMockKeycloakRole({ name: 'admin' })];
+      const strapiUser = createMockStrapiUser();
+
+      await service.removeRoles('realm-123', 'kc-user-123', roles, strapiUser);
+
+      expect(mockKeycloakClient.removeRoles).toHaveBeenCalled();
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.REMOVE_ROLE,
+          details: { roles: ['admin'] },
+        })
+      );
+    });
+
+    it('should require canManageRoles permission', async () => {
+      mockPermissionService.canAccessRealm.mockResolvedValue(false);
+      const strapiUser = createMockStrapiUser();
+
+      await expect(
+        service.assignRoles('realm-123', 'kc-user-123', [], strapiUser)
+      ).rejects.toThrow();
+    });
+  });
+
+  describe('bulkImport', () => {
+    it('should import users and track success/failure', async () => {
+      mockKeycloakClient.createUser
+        .mockResolvedValueOnce({ userId: 'user-1' })
+        .mockRejectedValueOnce({ sanitizedMessage: 'User exists' });
+      const strapiUser = createMockStrapiUser();
+      const users = [
+        { username: 'user1', email: 'user1@test.com' },
+        { username: 'user2', email: 'user2@test.com' },
+      ];
+
+      const result = await service.bulkImport('realm-123', users, strapiUser);
+
+      expect(result.success).toHaveLength(1);
+      expect(result.failed).toHaveLength(1);
+      expect(result.success[0].userId).toBe('user-1');
+      expect(result.failed[0].error).toBe('User exists');
+    });
+
+    it('should log bulk import action', async () => {
+      const strapiUser = createMockStrapiUser();
+
+      await service.bulkImport('realm-123', [{ username: 'test' }], strapiUser);
+
+      expect(mockAuditLogService.log).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: AUDIT_ACTIONS.BULK_IMPORT,
+          details: expect.objectContaining({
+            totalAttempted: 1,
+          }),
+        })
+      );
+    });
+  });
+
+  describe('exportUsers', () => {
+    it('should fetch all users in batches', async () => {
+      // First batch returns full batch, second returns partial
+      mockKeycloakClient.getUsers
+        .mockResolvedValueOnce(Array(PAGINATION.EXPORT_BATCH_SIZE).fill(createMockKeycloakUser()))
+        .mockResolvedValueOnce([createMockKeycloakUser()]);
+      const strapiUser = createMockStrapiUser();
+
+      const result = await service.exportUsers('realm-123', strapiUser);
+
+      expect(result).toHaveLength(PAGINATION.EXPORT_BATCH_SIZE + 1);
+      expect(mockKeycloakClient.getUsers).toHaveBeenCalledTimes(2);
+    });
+
+    it('should stop fetching when batch is not full', async () => {
+      mockKeycloakClient.getUsers.mockResolvedValue([createMockKeycloakUser()]);
+      const strapiUser = createMockStrapiUser();
+
+      await service.exportUsers('realm-123', strapiUser);
+
+      expect(mockKeycloakClient.getUsers).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/__tests__/utils/errors.test.mjs

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Unit tests for error utility functions.
+ * @module __tests__/utils/errors
+ */
+
+import {
+  createSanitizedError,
+  getErrorMessage,
+  isSanitizedError,
+} from '../../server/src/utils/errors.js';
+
+describe('Error Utilities', () => {
+  describe('createSanitizedError', () => {
+    it('should create an error with the internal message', () => {
+      const internalMsg = 'Internal error: connection timeout to 10.0.0.1:5432';
+      const sanitizedMsg = 'Database connection failed.';
+
+      const error = createSanitizedError(internalMsg, sanitizedMsg);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe(internalMsg);
+    });
+
+    it('should attach the sanitized message property', () => {
+      const internalMsg = 'Token fetch failed for client admin-cli: 401';
+      const sanitizedMsg = 'Authentication failed.';
+
+      const error = createSanitizedError(internalMsg, sanitizedMsg);
+
+      expect(error.sanitizedMessage).toBe(sanitizedMsg);
+    });
+
+    it('should be throwable', () => {
+      const error = createSanitizedError('internal', 'safe');
+
+      expect(() => {
+        throw error;
+      }).toThrow('internal');
+    });
+  });
+
+  describe('getErrorMessage', () => {
+    it('should return sanitized message when available', () => {
+      const error = createSanitizedError(
+        'Internal details: user_id=123',
+        'User not found.'
+      );
+
+      const message = getErrorMessage(error);
+
+      expect(message).toBe('User not found.');
+    });
+
+    it('should return original message when no sanitized message exists', () => {
+      const error = new Error('Standard error message');
+
+      const message = getErrorMessage(error);
+
+      expect(message).toBe('Standard error message');
+    });
+
+    it('should return fallback message when error has no message', () => {
+      const error = new Error();
+      error.message = '';
+
+      const message = getErrorMessage(error, 'Something went wrong');
+
+      expect(message).toBe('Something went wrong');
+    });
+
+    it('should use default fallback when no fallback provided', () => {
+      const error = new Error();
+      error.message = '';
+
+      const message = getErrorMessage(error);
+
+      expect(message).toBe('An unexpected error occurred');
+    });
+  });
+
+  describe('isSanitizedError', () => {
+    it('should return true for sanitized errors', () => {
+      const error = createSanitizedError('internal', 'safe');
+
+      expect(isSanitizedError(error)).toBe(true);
+    });
+
+    it('should return false for regular errors', () => {
+      const error = new Error('Regular error');
+
+      expect(isSanitizedError(error)).toBe(false);
+    });
+
+    it('should return false for null', () => {
+      expect(isSanitizedError(null)).toBe(false);
+    });
+
+    it('should return false for undefined', () => {
+      expect(isSanitizedError(undefined)).toBe(false);
+    });
+
+    it('should return false for non-string sanitizedMessage', () => {
+      const error = new Error('test');
+      error.sanitizedMessage = 123;
+
+      expect(isSanitizedError(error)).toBe(false);
+    });
+  });
+});

package/admin/src/components/Initializer.jsx

@@ -0,0 +1,14 @@
+import React, { useEffect, useRef } from 'react';
+import pluginId from '../pluginId';
+
+const Initializer = ({ setPlugin }) => {
+  const ref = useRef(setPlugin);
+
+  useEffect(() => {
+    ref.current(pluginId);
+  }, []);
+
+  return null;
+};
+
+export default Initializer;

package/admin/src/components/RealmBadge.jsx

@@ -0,0 +1,17 @@
+import { Badge } from '@strapi/design-system';
+
+const RealmBadge = ({ realm, size = 'S' }) => {
+  if (!realm) return null;
+
+  return (
+    <Badge
+      size={size}
+      backgroundColor={realm.color || 'primary600'}
+      textColor="neutral0"
+    >
+      {realm.displayName || realm.name}
+    </Badge>
+  );
+};
+
+export default RealmBadge;

package/admin/src/constants.js

@@ -0,0 +1,14 @@
+import pluginId from './pluginId';
+
+export const SERVER_PLUGIN_NAME = 'strapi-plugin-keycloak-realm-users';
+export const API_BASE_PATH = `/${SERVER_PLUGIN_NAME}`;
+
+export const getTrad = (id) => `${pluginId}.${id}`;
+
+export const PERMISSIONS = {
+  canRead: 'canRead',
+  canCreate: 'canCreate',
+  canUpdate: 'canUpdate',
+  canDelete: 'canDelete',
+  canManageRoles: 'canManageRoles',
+};