strapi-plugin-keycloak-realm-users 1.0.0

package/server/src/services/permission.js

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Permission management service for realm access control.
+ * Handles permission checking and realm admin assignments.
+ *
+ * @module services/permission
+ */
+
+import {
+  CONTENT_TYPES,
+  DEFAULT_REALM_PERMISSIONS,
+  STRAPI_SUPER_ADMIN_ROLE,
+} from '../constants.js';
+
+/**
+ * @typedef {Object} RealmPermissions
+ * @property {boolean} canRead - Can view users in the realm
+ * @property {boolean} canCreate - Can create new users
+ * @property {boolean} canUpdate - Can modify users (includes enable/disable)
+ * @property {boolean} canDelete - Can permanently delete users
+ * @property {boolean} canManageRoles - Can assign/remove realm roles
+ * @property {boolean} canResetPassword - Can reset passwords and send reset emails
+ */
+
+/**
+ * @typedef {Object} RealmAdminAssignment
+ * @property {string} documentId - Assignment document ID
+ * @property {number} strapiUserId - Strapi admin user ID
+ * @property {string} strapiUserEmail - Strapi admin email
+ * @property {RealmPermissions} permissions - Granted permissions
+ * @property {Object} [realmConfig] - Populated realm configuration
+ */
+
+/**
+ * @typedef {Object} StrapiUser
+ * @property {number} id - User ID
+ * @property {string} email - User email
+ * @property {Object[]} roles - Array of role objects
+ * @property {string} roles[].code - Role code
+ */
+
+/**
+ * Full permissions object for super admins.
+ * @constant {RealmPermissions}
+ * @private
+ */
+const SUPER_ADMIN_PERMISSIONS = {
+  canRead: true,
+  canCreate: true,
+  canUpdate: true,
+  canDelete: true,
+  canManageRoles: true,
+  canResetPassword: true,
+};
+
+/**
+ * Creates the permission service.
+ *
+ * @param {Object} params - Service parameters
+ * @param {Object} params.strapi - Strapi instance
+ * @returns {Object} Permission service methods
+ */
+const permissionService = ({ strapi }) => ({
+  /**
+   * Checks if a user has the Strapi super admin role.
+   * Super admins have unrestricted access to all realms and operations.
+   *
+   * @param {StrapiUser} user - Strapi user object with roles
+   * @returns {boolean} True if user is a super admin
+   *
+   * @example
+   * if (permissionService.isSuperAdmin(ctx.state.user)) {
+   *   // Allow unrestricted access
+   * }
+   */
+  isSuperAdmin(user) {
+    if (!user || !user.roles) return false;
+    return user.roles.some((role) => role.code === STRAPI_SUPER_ADMIN_ROLE);
+  },
+
+  /**
+   * Retrieves the realm admin assignment for a specific user and realm.
+   *
+   * @param {number} strapiUserId - Strapi user ID
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<RealmAdminAssignment|null>} Assignment or null if none exists
+   *
+   * @example
+   * const assignment = await permissionService.getRealmAdminAssignment(user.id, realmId);
+   * if (assignment?.permissions.canCreate) {
+   *   // User can create
+   * }
+   */
+  async getRealmAdminAssignment(strapiUserId, realmConfigId) {
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        strapiUserId,
+        realmConfig: { documentId: realmConfigId },
+      },
+      populate: ['realmConfig'],
+    });
+
+    return assignments[0] || null;
+  },
+
+  /**
+   * Checks if a user has a specific permission for a realm.
+   *
+   * @param {StrapiUser} user - Strapi user object
+   * @param {string} realmConfigId - Realm document ID
+   * @param {keyof RealmPermissions} [permission='canRead'] - Permission to check
+   * @returns {Promise<boolean>} True if user has the permission
+   *
+   * @example
+   * const canDelete = await permissionService.canAccessRealm(user, realmId, 'canDelete');
+   * if (!canDelete) {
+   *   throw new ForbiddenError();
+   * }
+   */
+  async canAccessRealm(user, realmConfigId, permission = 'canRead') {
+    // Super admins have all permissions
+    if (this.isSuperAdmin(user)) {
+      return true;
+    }
+
+    const assignment = await this.getRealmAdminAssignment(user.id, realmConfigId);
+
+    if (!assignment) {
+      return false;
+    }
+
+    const permissions = assignment.permissions || DEFAULT_REALM_PERMISSIONS;
+    return permissions[permission] === true;
+  },
+
+  /**
+   * Retrieves all realms accessible by a user with their permissions.
+   * Super admins see all enabled realms with full permissions.
+   * Regular users see only realms they're assigned to.
+   *
+   * @param {StrapiUser} user - Strapi user object
+   * @returns {Promise<Array<Object & {permissions: RealmPermissions}>>} Accessible realms with permissions
+   *
+   * @example
+   * const realms = await permissionService.getAccessibleRealms(ctx.state.user);
+   * // Returns realms with permissions attached
+   */
+  async getAccessibleRealms(user) {
+    // Super admins see all enabled realms with full permissions
+    if (this.isSuperAdmin(user)) {
+      const allRealms = await strapi.documents(CONTENT_TYPES.REALM_CONFIG).findMany({
+        filters: { enabled: true },
+        sort: { displayName: 'asc' },
+      });
+
+      return allRealms.map((realm) => ({
+        ...realm,
+        permissions: SUPER_ADMIN_PERMISSIONS,
+      }));
+    }
+
+    // Regular users see only assigned realms
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        strapiUserId: user.id,
+        realmConfig: { enabled: true },
+      },
+      populate: ['realmConfig'],
+    });
+
+    return assignments
+      .filter((assignment) => assignment.realmConfig)
+      .map((assignment) => ({
+        ...assignment.realmConfig,
+        permissions: assignment.permissions || DEFAULT_REALM_PERMISSIONS,
+      }));
+  },
+
+  /**
+   * Gets a user's specific permissions for a realm.
+   *
+   * @param {StrapiUser} user - Strapi user object
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<RealmPermissions|null>} User's permissions or null if no access
+   *
+   * @example
+   * const permissions = await permissionService.getRealmPermissions(user, realmId);
+   * if (permissions?.canUpdate) {
+   *   // Show edit button
+   * }
+   */
+  async getRealmPermissions(user, realmConfigId) {
+    if (this.isSuperAdmin(user)) {
+      return SUPER_ADMIN_PERMISSIONS;
+    }
+
+    const assignment = await this.getRealmAdminAssignment(user.id, realmConfigId);
+    return assignment?.permissions || null;
+  },
+
+  /**
+   * Assigns a Strapi user to a realm with specified permissions.
+   * If an assignment already exists, it updates the permissions.
+   *
+   * @param {number} strapiUserId - Strapi user ID to assign
+   * @param {string} strapiUserEmail - User's email for reference
+   * @param {string} realmConfigId - Realm document ID
+   * @param {Partial<RealmPermissions>} [permissions={}] - Permissions to grant
+   * @returns {Promise<RealmAdminAssignment>} Created or updated assignment
+   *
+   * @example
+   * await permissionService.assignUserToRealm(
+   *   userId,
+   *   'admin@example.com',
+   *   realmId,
+   *   { canRead: true, canCreate: true, canUpdate: true }
+   * );
+   */
+  async assignUserToRealm(strapiUserId, strapiUserEmail, realmConfigId, permissions = {}) {
+    // Check for existing assignment
+    const existing = await this.getRealmAdminAssignment(strapiUserId, realmConfigId);
+
+    // Merge with default permissions
+    const mergedPermissions = { ...DEFAULT_REALM_PERMISSIONS, ...permissions };
+
+    if (existing) {
+      // Update existing assignment
+      return strapi.documents(CONTENT_TYPES.REALM_ADMIN).update({
+        documentId: existing.documentId,
+        data: {
+          permissions: mergedPermissions,
+        },
+      });
+    }
+
+    // Create new assignment
+    return strapi.documents(CONTENT_TYPES.REALM_ADMIN).create({
+      data: {
+        strapiUserId,
+        strapiUserEmail,
+        realmConfig: realmConfigId,
+        permissions: mergedPermissions,
+      },
+    });
+  },
+
+  /**
+   * Removes a user's access to a realm.
+   *
+   * @param {number} strapiUserId - Strapi user ID
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<boolean>} True if assignment was removed, false if none existed
+   *
+   * @example
+   * const removed = await permissionService.removeUserFromRealm(userId, realmId);
+   */
+  async removeUserFromRealm(strapiUserId, realmConfigId) {
+    const assignment = await this.getRealmAdminAssignment(strapiUserId, realmConfigId);
+
+    if (assignment) {
+      await strapi.documents(CONTENT_TYPES.REALM_ADMIN).delete({
+        documentId: assignment.documentId,
+      });
+      return true;
+    }
+
+    return false;
+  },
+
+  /**
+   * Retrieves all admin assignments for a specific realm.
+   *
+   * @param {string} realmConfigId - Realm document ID
+   * @returns {Promise<RealmAdminAssignment[]>} Array of admin assignments
+   *
+   * @example
+   * const admins = await permissionService.getRealmAdmins(realmId);
+   * // Display list of users who can manage this realm
+   */
+  async getRealmAdmins(realmConfigId) {
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        realmConfig: { documentId: realmConfigId },
+      },
+    });
+
+    return assignments;
+  },
+});
+
+export default permissionService;

package/server/src/services/realm.js

@@ -0,0 +1,374 @@
+/**
+ * @fileoverview Realm configuration management service.
+ * Handles CRUD operations for Keycloak realm configurations stored in Strapi.
+ *
+ * @module services/realm
+ */
+
+import {
+  PLUGIN_ID,
+  CONTENT_TYPES,
+  SERVICES,
+  ERROR_MESSAGES,
+  DEFAULT_REALM_COLOR,
+  REALM_NAME_PATTERN,
+} from '../constants.js';
+import { createSanitizedError } from '../utils/errors.js';
+
+/**
+ * @typedef {Object} RealmConfigData
+ * @property {string} name - Unique slug identifier (lowercase, hyphens only)
+ * @property {string} displayName - Human-readable name for UI
+ * @property {string} serverUrl - Keycloak server base URL
+ * @property {string} realmName - Keycloak realm name
+ * @property {string} clientId - Service account client ID
+ * @property {string} [clientSecret] - Service account client secret
+ * @property {boolean} [enabled=true] - Whether realm is active
+ * @property {string} [color] - UI accent color (hex)
+ */
+
+/**
+ * @typedef {Object} RealmConfig
+ * @property {string} documentId - Strapi document ID
+ * @property {string} name - Unique slug identifier
+ * @property {string} displayName - Human-readable name
+ * @property {string} serverUrl - Keycloak server URL
+ * @property {string} realmName - Keycloak realm name
+ * @property {string} clientId - Client ID
+ * @property {boolean} enabled - Active status
+ * @property {string} color - UI color
+ * @property {Date} createdAt - Creation timestamp
+ * @property {Date} updatedAt - Last update timestamp
+ */
+
+/**
+ * Creates the realm configuration service.
+ *
+ * @param {Object} params - Service parameters
+ * @param {Object} params.strapi - Strapi instance
+ * @returns {Object} Realm service methods
+ */
+const realmService = ({ strapi }) => ({
+  /**
+   * Gets the Keycloak client service instance.
+   *
+   * @returns {Object} Keycloak client service
+   * @private
+   */
+  get keycloakClient() {
+    return strapi.plugin(PLUGIN_ID).service(SERVICES.KEYCLOAK_CLIENT);
+  },
+
+  /**
+   * Retrieves all realm configurations.
+   * Note: clientSecret is not included in results (private field).
+   *
+   * @returns {Promise<RealmConfig[]>} Array of realm configurations sorted by displayName
+   *
+   * @example
+   * const realms = await realmService.findAll();
+   */
+  async findAll() {
+    return strapi.documents(CONTENT_TYPES.REALM_CONFIG).findMany({
+      sort: { displayName: 'asc' },
+    });
+  },
+
+  /**
+   * Retrieves a single realm by document ID.
+   * Note: clientSecret is not included (private field).
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<RealmConfig>} Realm configuration
+   * @throws {Error} If realm not found
+   *
+   * @example
+   * const realm = await realmService.findOne('abc123');
+   */
+  async findOne(documentId) {
+    const realm = await strapi.documents(CONTENT_TYPES.REALM_CONFIG).findOne({
+      documentId,
+    });
+
+    if (!realm) {
+      throw createSanitizedError(
+        `Realm ${documentId} not found`,
+        ERROR_MESSAGES.REALM_NOT_FOUND
+      );
+    }
+
+    return realm;
+  },
+
+  /**
+   * Retrieves a realm with its clientSecret for internal Keycloak API calls.
+   * Uses db.query to bypass Strapi's private field sanitization.
+   *
+   * SECURITY: Only use this method when the clientSecret is actually needed
+   * for Keycloak authentication. Never expose the result to API responses.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<RealmConfig & {clientSecret: string}>} Full realm config with secret
+   * @throws {Error} If realm not found
+   *
+   * @example
+   * // Internal use only - for Keycloak API calls
+   * const realm = await realmService.findOneWithSecret(documentId);
+   * const token = await keycloakClient.getAccessToken(realm);
+   */
+  async findOneWithSecret(documentId) {
+    const realm = await strapi.db.query(CONTENT_TYPES.REALM_CONFIG).findOne({
+      where: { documentId },
+    });
+
+    if (!realm) {
+      throw createSanitizedError(
+        `Realm ${documentId} not found`,
+        ERROR_MESSAGES.REALM_NOT_FOUND
+      );
+    }
+
+    return realm;
+  },
+
+  /**
+   * Finds a realm by its unique slug name.
+   *
+   * @param {string} name - Realm slug name
+   * @returns {Promise<RealmConfig|null>} Realm configuration or null if not found
+   *
+   * @example
+   * const realm = await realmService.findByName('production-users');
+   */
+  async findByName(name) {
+    const realms = await strapi.documents(CONTENT_TYPES.REALM_CONFIG).findMany({
+      filters: { name },
+    });
+
+    return realms[0] || null;
+  },
+
+  /**
+   * Validates realm name format.
+   *
+   * @param {string} name - Name to validate
+   * @returns {boolean} True if valid
+   * @private
+   */
+  isValidName(name) {
+    return REALM_NAME_PATTERN.test(name);
+  },
+
+  /**
+   * Normalizes a server URL by removing trailing slashes.
+   *
+   * @param {string} url - URL to normalize
+   * @returns {string} Normalized URL
+   * @private
+   */
+  normalizeServerUrl(url) {
+    return url.replace(/\/$/, '');
+  },
+
+  /**
+   * Creates a new realm configuration.
+   *
+   * @param {RealmConfigData} data - Realm configuration data
+   * @returns {Promise<RealmConfig>} Created realm configuration
+   * @throws {Error} If validation fails or name already exists
+   *
+   * @example
+   * const realm = await realmService.create({
+   *   name: 'production-users',
+   *   displayName: 'Production Users',
+   *   serverUrl: 'https://keycloak.example.com',
+   *   realmName: 'production',
+   *   clientId: 'strapi-admin',
+   *   clientSecret: 'secret-value'
+   * });
+   */
+  async create(data) {
+    const { name, displayName, serverUrl, realmName, clientId, clientSecret } = data;
+
+    // Validate required fields
+    if (!name || !displayName || !serverUrl || !realmName || !clientId) {
+      throw createSanitizedError(
+        'Missing required fields',
+        ERROR_MESSAGES.MISSING_REQUIRED_FIELDS
+      );
+    }
+
+    // Validate name format
+    if (!this.isValidName(name)) {
+      throw createSanitizedError(
+        `Invalid name format: ${name}`,
+        ERROR_MESSAGES.INVALID_NAME_FORMAT
+      );
+    }
+
+    // Check for duplicate name
+    const existing = await this.findByName(name);
+    if (existing) {
+      throw createSanitizedError(
+        `Realm with name ${name} already exists`,
+        ERROR_MESSAGES.REALM_NAME_EXISTS
+      );
+    }
+
+    return strapi.documents(CONTENT_TYPES.REALM_CONFIG).create({
+      data: {
+        name,
+        displayName,
+        serverUrl: this.normalizeServerUrl(serverUrl),
+        realmName,
+        clientId,
+        clientSecret: clientSecret || null,
+        enabled: data.enabled !== false,
+        color: data.color || DEFAULT_REALM_COLOR,
+      },
+    });
+  },
+
+  /**
+   * Updates an existing realm configuration.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @param {Partial<RealmConfigData>} data - Fields to update
+   * @returns {Promise<RealmConfig>} Updated realm configuration
+   * @throws {Error} If validation fails or realm not found
+   *
+   * @example
+   * const updated = await realmService.update(documentId, {
+   *   displayName: 'New Display Name',
+   *   enabled: false
+   * });
+   */
+  async update(documentId, data) {
+    const existing = await this.findOne(documentId);
+
+    // Validate name change if applicable
+    if (data.name && data.name !== existing.name) {
+      if (!this.isValidName(data.name)) {
+        throw createSanitizedError(
+          `Invalid name format: ${data.name}`,
+          ERROR_MESSAGES.INVALID_NAME_FORMAT
+        );
+      }
+
+      const duplicate = await this.findByName(data.name);
+      if (duplicate && duplicate.documentId !== documentId) {
+        throw createSanitizedError(
+          `Realm with name ${data.name} already exists`,
+          ERROR_MESSAGES.REALM_NAME_EXISTS
+        );
+      }
+    }
+
+    // Prepare update data
+    const updateData = { ...data };
+    if (updateData.serverUrl) {
+      updateData.serverUrl = this.normalizeServerUrl(updateData.serverUrl);
+    }
+
+    // Clear token cache if connection details changed
+    const connectionFieldsChanged =
+      updateData.serverUrl ||
+      updateData.realmName ||
+      updateData.clientId ||
+      updateData.clientSecret;
+
+    if (connectionFieldsChanged) {
+      this.keycloakClient.clearTokenCache(existing);
+    }
+
+    return strapi.documents(CONTENT_TYPES.REALM_CONFIG).update({
+      documentId,
+      data: updateData,
+    });
+  },
+
+  /**
+   * Deletes a realm configuration and all associated admin assignments.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<{success: boolean}>} Success indicator
+   * @throws {Error} If realm not found
+   *
+   * @example
+   * await realmService.delete(documentId);
+   */
+  async delete(documentId) {
+    const realm = await this.findOne(documentId);
+
+    // Clear token cache
+    this.keycloakClient.clearTokenCache(realm);
+
+    // Delete all realm admin assignments for this realm
+    const assignments = await strapi.documents(CONTENT_TYPES.REALM_ADMIN).findMany({
+      filters: {
+        realmConfig: { documentId },
+      },
+    });
+
+    // Delete assignments sequentially to avoid race conditions
+    for (const assignment of assignments) {
+      await strapi.documents(CONTENT_TYPES.REALM_ADMIN).delete({
+        documentId: assignment.documentId,
+      });
+    }
+
+    // Delete the realm config
+    await strapi.documents(CONTENT_TYPES.REALM_CONFIG).delete({
+      documentId,
+    });
+
+    return { success: true };
+  },
+
+  /**
+   * Tests connection to a saved realm configuration.
+   *
+   * @param {string} documentId - Strapi document ID
+   * @returns {Promise<{success: boolean, message?: string, realmDisplayName?: string}>} Test result
+   *
+   * @example
+   * const result = await realmService.testConnection(documentId);
+   * if (result.success) {
+   *   console.log(`Connected to ${result.realmDisplayName}`);
+   * } else {
+   *   console.error(result.message);
+   * }
+   */
+  async testConnection(documentId) {
+    const realmBasic = await this.findOne(documentId);
+
+    if (!realmBasic.enabled) {
+      return { success: false, message: ERROR_MESSAGES.REALM_DISABLED };
+    }
+
+    // Get realm with clientSecret for Keycloak connection
+    const realm = await this.findOneWithSecret(documentId);
+    return this.keycloakClient.testConnection(realm);
+  },
+
+  /**
+   * Tests connection with raw configuration data (before saving).
+   * Useful for validating credentials during realm creation/editing.
+   *
+   * @param {RealmConfigData} config - Raw realm configuration
+   * @returns {Promise<{success: boolean, message?: string, realmDisplayName?: string}>} Test result
+   *
+   * @example
+   * const result = await realmService.testConnectionRaw({
+   *   serverUrl: 'https://keycloak.example.com',
+   *   realmName: 'my-realm',
+   *   clientId: 'strapi-admin',
+   *   clientSecret: 'secret'
+   * });
+   */
+  async testConnectionRaw(config) {
+    return this.keycloakClient.testConnection(config);
+  },
+});
+
+export default realmService;