strapi-plugin-keycloak-realm-users 1.0.0

package/jest.config.cjs

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Jest configuration for strapi-plugin-keycloak-realm-users.
+ * Uses Babel for ES module transformation.
+ * @see https://jestjs.io/docs/configuration
+ */
+
+module.exports = {
+  testEnvironment: 'node',
+
+  // Use Babel to transform ES modules
+  transform: {
+    '^.+\\.m?js$': 'babel-jest',
+  },
+
+  // Don't ignore server/src when transforming
+  transformIgnorePatterns: [
+    '/node_modules/',
+  ],
+
+  // Test file patterns
+  testMatch: [
+    '**/__tests__/**/*.test.mjs',
+  ],
+
+  // Coverage configuration - focus on services and utils (tested modules)
+  collectCoverageFrom: [
+    'server/src/services/*.js',
+    'server/src/utils/*.js',
+    'server/src/constants.js',
+    '!server/src/services/index.js',
+    '!server/src/utils/index.js',
+    '!**/node_modules/**',
+  ],
+
+  // Coverage thresholds for tested modules
+  coverageThreshold: {
+    global: {
+      branches: 75,
+      functions: 95,
+      lines: 90,
+      statements: 90,
+    },
+  },
+
+  // Clear mocks between tests
+  clearMocks: true,
+
+  // Verbose output
+  verbose: true,
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "strapi-plugin-keycloak-realm-users",
+  "version": "1.0.0",
+  "description": "Strapi plugin for managing Keycloak users across multiple realms with role-based access control",
+  "license": "MIT",
+  "strapi": {
+    "name": "keycloak-realm-users",
+    "displayName": "Keycloak Realm Users",
+    "description": "Manage Keycloak users across multiple realms",
+    "kind": "plugin"
+  },
+  "type": "commonjs",
+  "exports": {
+    "./strapi-admin": {
+      "types": "./dist/admin/src/index.d.ts",
+      "source": "./admin/src/index.js",
+      "import": "./dist/admin/index.mjs",
+      "require": "./dist/admin/index.js",
+      "default": "./dist/admin/index.js"
+    },
+    "./strapi-server": {
+      "types": "./dist/server/src/index.d.ts",
+      "source": "./server/src/index.js",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "strapi-plugin build",
+    "watch": "strapi-plugin watch",
+    "verify": "strapi-plugin verify",
+    "test": "jest --config jest.config.cjs",
+    "test:watch": "jest --config jest.config.cjs --watch",
+    "test:coverage": "jest --config jest.config.cjs --coverage"
+  },
+  "peerDependencies": {
+    "@strapi/strapi": "^5.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/preset-env": "^7.29.0",
+    "@strapi/sdk-plugin": "^5.0.0",
+    "babel-jest": "^30.2.0",
+    "jest": "^29.7.0"
+  },
+  "dependencies": {
+    "@strapi/design-system": "^2.1.2",
+    "@strapi/icons": "^2.1.2",
+    "react": "^19.2.4",
+    "react-intl": "^8.1.3",
+    "react-router-dom": "^7.13.0"
+  }
+}

package/server/src/bootstrap.js

@@ -0,0 +1,87 @@
+import { PLUGIN_ID } from './constants.js';
+
+const bootstrap = async ({ strapi }) => {
+  // Register custom actions for RBAC
+  try {
+    await strapi.admin.services.permission.actionProvider.registerMany([
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.read`,
+        displayName: 'Read Realms',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Realms',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.create`,
+        displayName: 'Create Realms',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Realms',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.update`,
+        displayName: 'Update Realms',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Realms',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.realm.delete`,
+        displayName: 'Delete Realms',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Realms',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.read`,
+        displayName: 'Read Keycloak Users',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Users',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.create`,
+        displayName: 'Create Keycloak Users',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Users',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.update`,
+        displayName: 'Update Keycloak Users',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Users',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.user.delete`,
+        displayName: 'Delete Keycloak Users',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Users',
+      },
+      {
+        uid: `plugin::${PLUGIN_ID}.audit.read`,
+        displayName: 'Read Audit Logs',
+        pluginName: PLUGIN_ID,
+        section: 'settings',
+        category: 'Keycloak User Management',
+        subCategory: 'Audit',
+      },
+    ]);
+
+    strapi.log.info(`[${PLUGIN_ID}] Plugin bootstrapped with permissions registered`);
+  } catch (err) {
+    strapi.log.error(`[${PLUGIN_ID}] Failed to register permissions:`, err);
+  }
+};
+
+export default bootstrap;

package/server/src/config/index.js

@@ -0,0 +1,7 @@
+export default {
+  default: {},
+  validator(config) {
+    // No runtime config validation needed
+    // Realm configurations are stored in the database
+  },
+};

package/server/src/constants.js

@@ -0,0 +1,255 @@
+/**
+ * @fileoverview Constants and configuration values for the Keycloak Realm Users plugin.
+ * All magic values, identifiers, and configurable defaults are centralized here.
+ * @module constants
+ */
+
+// ============================================================================
+// Plugin Identification
+// ============================================================================
+
+/**
+ * Unique plugin identifier used for Strapi registration.
+ * @constant {string}
+ */
+export const PLUGIN_ID = 'strapi-plugin-keycloak-realm-users';
+
+// ============================================================================
+// Content Type Identifiers
+// ============================================================================
+
+/**
+ * Strapi content type UIDs for plugin entities.
+ * @constant {Object}
+ * @property {string} REALM_CONFIG - Realm configuration content type
+ * @property {string} REALM_ADMIN - Realm admin assignment content type
+ * @property {string} AUDIT_LOG - Audit log entry content type
+ */
+export const CONTENT_TYPES = {
+  REALM_CONFIG: `plugin::${PLUGIN_ID}.realm-config`,
+  REALM_ADMIN: `plugin::${PLUGIN_ID}.realm-admin`,
+  AUDIT_LOG: `plugin::${PLUGIN_ID}.audit-log`,
+};
+
+// ============================================================================
+// Service Identifiers
+// ============================================================================
+
+/**
+ * Service names for internal plugin service resolution.
+ * @constant {Object}
+ * @property {string} REALM - Realm management service
+ * @property {string} KEYCLOAK_CLIENT - Keycloak API client service
+ * @property {string} USER - User management service
+ * @property {string} PERMISSION - Permission checking service
+ * @property {string} AUDIT_LOG - Audit logging service
+ */
+export const SERVICES = {
+  REALM: 'realm',
+  KEYCLOAK_CLIENT: 'keycloak-client',
+  USER: 'user',
+  PERMISSION: 'permission',
+  AUDIT_LOG: 'audit-log',
+};
+
+// ============================================================================
+// Audit Action Types
+// ============================================================================
+
+/**
+ * Action types recorded in the audit log.
+ * @constant {Object}
+ */
+export const AUDIT_ACTIONS = {
+  /** User was created in Keycloak */
+  CREATE_USER: 'CREATE_USER',
+  /** User details were modified */
+  UPDATE_USER: 'UPDATE_USER',
+  /** User was permanently deleted */
+  DELETE_USER: 'DELETE_USER',
+  /** User password was reset */
+  RESET_PASSWORD: 'RESET_PASSWORD',
+  /** Realm role was assigned to user */
+  ASSIGN_ROLE: 'ASSIGN_ROLE',
+  /** Realm role was removed from user */
+  REMOVE_ROLE: 'REMOVE_ROLE',
+  /** User account was enabled */
+  ENABLE_USER: 'ENABLE_USER',
+  /** User account was disabled */
+  DISABLE_USER: 'DISABLE_USER',
+  /** Email verification was sent */
+  SEND_VERIFY_EMAIL: 'SEND_VERIFY_EMAIL',
+  /** Password reset email was sent */
+  SEND_RESET_PASSWORD_EMAIL: 'SEND_RESET_PASSWORD_EMAIL',
+  /** Bulk user import was performed */
+  BULK_IMPORT: 'BULK_IMPORT',
+};
+
+// ============================================================================
+// Error Messages (User-Safe)
+// ============================================================================
+
+/**
+ * Sanitized error messages safe for API responses.
+ * Internal error details are logged separately for debugging.
+ * @constant {Object}
+ */
+export const ERROR_MESSAGES = {
+  REALM_NOT_FOUND: 'Realm configuration not found.',
+  REALM_DISABLED: 'This realm is currently disabled.',
+  USER_NOT_FOUND: 'Keycloak user not found.',
+  INSUFFICIENT_PERMISSIONS: 'You do not have permission to perform this action.',
+  REALM_ACCESS_DENIED: 'You do not have access to this realm.',
+  KEYCLOAK_CONNECTION_FAILED: 'Failed to connect to Keycloak server.',
+  KEYCLOAK_AUTH_FAILED: 'Failed to authenticate with Keycloak.',
+  INVALID_USER_DATA: 'Invalid user data provided.',
+  MISSING_REQUIRED_FIELDS: 'Missing required fields.',
+  UNKNOWN_ERROR: 'An unexpected error occurred.',
+  USER_ALREADY_EXISTS: 'A user with this username or email already exists.',
+  PASSWORD_RESET_FAILED: 'Failed to reset password.',
+  EMAIL_SEND_FAILED: 'Failed to send email.',
+  ROLE_ASSIGNMENT_FAILED: 'Failed to assign roles.',
+  ROLE_REMOVAL_FAILED: 'Failed to remove roles.',
+  LOGOUT_FAILED: 'Failed to logout user.',
+  INVALID_NAME_FORMAT: 'Name must contain only lowercase letters, numbers, and hyphens.',
+  REALM_NAME_EXISTS: 'A realm with this name already exists.',
+};
+
+// ============================================================================
+// Default Permissions
+// ============================================================================
+
+/**
+ * Default permissions for realm admin assignments.
+ * New realm admins receive read-only access by default.
+ * @constant {Object}
+ * @property {boolean} canRead - Can view users in the realm
+ * @property {boolean} canCreate - Can create new users
+ * @property {boolean} canUpdate - Can modify existing users (includes enable/disable)
+ * @property {boolean} canDelete - Can permanently delete users
+ * @property {boolean} canManageRoles - Can assign/remove realm roles
+ * @property {boolean} canResetPassword - Can reset user passwords and send password reset emails
+ */
+export const DEFAULT_REALM_PERMISSIONS = {
+  canRead: true,
+  canCreate: false,
+  canUpdate: false,
+  canDelete: false,
+  canManageRoles: false,
+  canResetPassword: false,
+};
+
+// ============================================================================
+// Strapi Role Constants
+// ============================================================================
+
+/**
+ * Strapi admin role code for super administrators.
+ * Super admins have unrestricted access to all plugin functionality.
+ * @constant {string}
+ */
+export const STRAPI_SUPER_ADMIN_ROLE = 'strapi-super-admin';
+
+// ============================================================================
+// Keycloak Configuration
+// ============================================================================
+
+/**
+ * Time buffer (in milliseconds) before token expiry to trigger refresh.
+ * Tokens are refreshed 60 seconds before expiration to prevent request failures.
+ * @constant {number}
+ */
+export const TOKEN_EXPIRY_BUFFER_MS = 60000;
+
+/**
+ * Default lifespan (in seconds) for email action links sent to users.
+ * Default: 12 hours (43200 seconds)
+ * @constant {number}
+ */
+export const EMAIL_ACTION_LIFESPAN_SECONDS = 43200;
+
+/**
+ * Default color for realm UI badge/indicator.
+ * @constant {string}
+ */
+export const DEFAULT_REALM_COLOR = '#4945ff';
+
+// ============================================================================
+// Pagination Defaults
+// ============================================================================
+
+/**
+ * Default pagination settings for list operations.
+ * @constant {Object}
+ * @property {number} PAGE_SIZE - Default number of items per page
+ * @property {number} AUDIT_LOG_LIMIT - Default limit for audit log queries
+ * @property {number} EXPORT_BATCH_SIZE - Batch size for user export operations
+ */
+export const PAGINATION = {
+  PAGE_SIZE: 25,
+  AUDIT_LOG_LIMIT: 50,
+  EXPORT_BATCH_SIZE: 100,
+};
+
+// ============================================================================
+// HTTP Constants
+// ============================================================================
+
+/**
+ * HTTP status codes used for error handling.
+ * @constant {Object}
+ */
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  INTERNAL_ERROR: 500,
+};
+
+/**
+ * HTTP headers used in Keycloak API requests.
+ * @constant {Object}
+ */
+export const HTTP_HEADERS = {
+  CONTENT_TYPE_JSON: 'application/json',
+  CONTENT_TYPE_FORM: 'application/x-www-form-urlencoded',
+};
+
+// ============================================================================
+// Keycloak Email Actions
+// ============================================================================
+
+/**
+ * Keycloak required action types for email operations.
+ * @constant {Object}
+ */
+export const KEYCLOAK_EMAIL_ACTIONS = {
+  VERIFY_EMAIL: 'VERIFY_EMAIL',
+  UPDATE_PASSWORD: 'UPDATE_PASSWORD',
+};
+
+// ============================================================================
+// Validation Patterns
+// ============================================================================
+
+/**
+ * Regex pattern for validating realm slug names.
+ * Allows only lowercase letters, numbers, and hyphens.
+ * @constant {RegExp}
+ */
+export const REALM_NAME_PATTERN = /^[a-z0-9-]+$/;
+
+// ============================================================================
+// Default Values
+// ============================================================================
+
+/**
+ * Placeholder value for unknown user emails in audit logs.
+ * @constant {string}
+ */
+export const UNKNOWN_USER_EMAIL = 'unknown';

package/server/src/content-types/audit-log/index.js

@@ -0,0 +1,3 @@
+import schema from './schema.json';
+
+export default { schema };

package/server/src/content-types/audit-log/schema.json

@@ -0,0 +1,61 @@
+{
+  "kind": "collectionType",
+  "collectionName": "kru_audit_logs",
+  "info": {
+    "singularName": "audit-log",
+    "pluralName": "audit-logs",
+    "displayName": "Keycloak Audit Log"
+  },
+  "options": {
+    "draftAndPublish": false
+  },
+  "pluginOptions": {
+    "content-manager": {
+      "visible": true
+    },
+    "content-type-builder": {
+      "visible": false
+    }
+  },
+  "attributes": {
+    "realmName": {
+      "type": "string",
+      "required": true
+    },
+    "realmDisplayName": {
+      "type": "string"
+    },
+    "action": {
+      "type": "enumeration",
+      "enum": [
+        "CREATE_USER",
+        "UPDATE_USER",
+        "DELETE_USER",
+        "RESET_PASSWORD",
+        "ASSIGN_ROLE",
+        "REMOVE_ROLE",
+        "ENABLE_USER",
+        "DISABLE_USER",
+        "SEND_VERIFY_EMAIL",
+        "SEND_RESET_PASSWORD_EMAIL",
+        "BULK_IMPORT"
+      ],
+      "required": true
+    },
+    "keycloakUserId": {
+      "type": "string"
+    },
+    "keycloakUsername": {
+      "type": "string"
+    },
+    "details": {
+      "type": "json"
+    },
+    "performedById": {
+      "type": "integer"
+    },
+    "performedByEmail": {
+      "type": "string"
+    }
+  }
+}

package/server/src/content-types/index.js

@@ -0,0 +1,9 @@
+import realmConfig from './realm-config';
+import realmAdmin from './realm-admin';
+import auditLog from './audit-log';
+
+export default {
+  'realm-config': realmConfig,
+  'realm-admin': realmAdmin,
+  'audit-log': auditLog,
+};

package/server/src/content-types/realm-admin/index.js

@@ -0,0 +1,3 @@
+import schema from './schema.json';
+
+export default { schema };

package/server/src/content-types/realm-admin/schema.json

@@ -0,0 +1,45 @@
+{
+  "kind": "collectionType",
+  "collectionName": "kru_realm_admins",
+  "info": {
+    "singularName": "realm-admin",
+    "pluralName": "realm-admins",
+    "displayName": "Realm Admin Assignment"
+  },
+  "options": {
+    "draftAndPublish": false
+  },
+  "pluginOptions": {
+    "content-manager": {
+      "visible": false
+    },
+    "content-type-builder": {
+      "visible": false
+    }
+  },
+  "attributes": {
+    "strapiUserId": {
+      "type": "integer",
+      "required": true
+    },
+    "strapiUserEmail": {
+      "type": "string"
+    },
+    "realmConfig": {
+      "type": "relation",
+      "relation": "manyToOne",
+      "target": "plugin::strapi-plugin-keycloak-realm-users.realm-config"
+    },
+    "permissions": {
+      "type": "json",
+      "default": {
+        "canRead": true,
+        "canCreate": false,
+        "canUpdate": false,
+        "canDelete": false,
+        "canManageRoles": false,
+        "canResetPassword": false
+      }
+    }
+  }
+}

package/server/src/content-types/realm-config/index.js

@@ -0,0 +1,3 @@
+import schema from './schema.json';
+
+export default { schema };

package/server/src/content-types/realm-config/schema.json

@@ -0,0 +1,56 @@
+{
+  "kind": "collectionType",
+  "collectionName": "kru_realm_configs",
+  "info": {
+    "singularName": "realm-config",
+    "pluralName": "realm-configs",
+    "displayName": "Keycloak Realm"
+  },
+  "options": {
+    "draftAndPublish": false
+  },
+  "pluginOptions": {
+    "content-manager": {
+      "visible": false
+    },
+    "content-type-builder": {
+      "visible": false
+    }
+  },
+  "attributes": {
+    "name": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "regex": "^[a-z0-9-]+$"
+    },
+    "displayName": {
+      "type": "string",
+      "required": true
+    },
+    "serverUrl": {
+      "type": "string",
+      "required": true
+    },
+    "realmName": {
+      "type": "string",
+      "required": true
+    },
+    "clientId": {
+      "type": "string",
+      "required": true
+    },
+    "clientSecret": {
+      "type": "string",
+      "private": true
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true
+    },
+    "color": {
+      "type": "string",
+      "default": "#4945ff"
+    }
+  }
+}