two_percent 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1f5dcfb8d7346d8f08d3b4a10b9d9e53f89a31717b03e202653deaaadedeb81
-  data.tar.gz: 10345fe74093b552ef36c20710412fa84b0b826ffd6ea22803fb49eea73105f1
+  metadata.gz: 4ac252e6553e3c0c261a4040213a21c79a68676d11a5f62acd3b6400bc391f44
+  data.tar.gz: 4bd46dfb3b2017945cff1e9abca2549634f4d4d68facc8290a5e2345b4264ad1
 SHA512:
-  metadata.gz: 596d23c098e8053360b2d5bf79f683f37cb0f476ca74ef50d3e6c45767871ebc178e8d5222cac35327c804a2b2ec8f6ce461035534c8bc8930c2079b0345bee0
-  data.tar.gz: 4991c89a19e03a7c6ab431cc52e6cc6e629a8a3b462bf4d9b5e577a0ece8e30d35d4df7d6d84c01bed40ff939cfbdedddea8e448bebe305368b6cbbe40db119b
+  metadata.gz: b3b842f8a44b3b5c58ebc4d9597468a70c970a70550d3a3b64d67f54c88dc67484eb9b30599cc4274db5674584318535fc38a84060b930c25661044938407ef3
+  data.tar.gz: bfe00f93654f7848d59d43610d70cb018a93f65d13663988a066761fa8291e65014712b54306d7211dfb28fb0f3fe6ae50ca99faa13c71ec3faf75d64f7e630f

data/app/controllers/two_percent/application_controller.rb

@@ -8,6 +8,7 @@ module TwoPercent
     rescue_from ActiveRecord::RecordNotFound, with: :handle_record_not_found
     rescue_from ActiveRecord::RecordInvalid, with: :handle_validation_error
     rescue_from ArgumentError, with: :handle_bad_request
+    rescue_from TwoPercent::ReadOnlyAttributeError, with: :handle_read_only_attribute
 
     def authenticate
       result = instance_exec(&TwoPercent.config.authenticate)
@@ -54,6 +55,15 @@ module TwoPercent
       )
     end
 
+    def handle_read_only_attribute(exception)
+      # RFC 7644 Section 3.5.2: Read-only attribute modification attempt
+      render_scim_error(
+        status: :bad_request,
+        scim_type: "mutability",
+        detail: exception.message
+      )
+    end
+
     def extract_correlation_id
       header_name = TwoPercent.config.correlation_id_header
       @correlation_id = request.headers[header_name] || SecureRandom.uuid

data/app/controllers/two_percent/scim_controller.rb

@@ -2,6 +2,8 @@
 
 module TwoPercent
   class ScimController < ApplicationController
+    include TwoPercent::ValidatesUserGroupsPatch
+
     def create
       record = with_scim_logging("create") do
         # Persist to two_percent tables first (validates SCIM schema)
@@ -25,6 +27,14 @@ module TwoPercent
         # Find existing record
         record = find_scim_record(params[:id])
 
+        # Sync scim_data["members"] from join table for Groups to ensure data consistency
+        # Must happen BEFORE PatchProcessor reads scim_data to ensure PATCH operations
+        # are applied to current members, not stale/empty data
+        record.scim_data["members"] = record.members_for_patch if group_resource?
+
+        # Validate RFC 7643 read-only attributes before processing
+        validate_patch_operations!(params[:resource_type], scim_params) if user_resource?
+
         # Apply SCIM PATCH operations (RFC 7644 compliance)
         processor = TwoPercent::Scim::PatchProcessor.new(scim_params)
         current_scim_data = record.scim_data || {}
@@ -34,8 +44,10 @@ module TwoPercent
         patched_data["id"] = params[:id] # Ensure ID is present
         updated_record = persist_scim_record(patched_data)
 
-        # Reload with associations for domain event and response
-        updated_record = reload_with_members(updated_record)
+        # Reload associations for response
+        # Users: always reload (cheap - few groups per user)
+        # Groups: conditionally reload based on config (expensive - thousands of members)
+        updated_record = reload_with_members(updated_record) if user_resource? || should_reload_members?(updated_record)
 
         # Publish domain event with final state
         publish_updated_event(updated_record)
@@ -255,6 +267,16 @@ module TwoPercent
       model_class.includes(association_name).find(record.id)
     end
 
+    # Check if group members should be reloaded for PATCH response
+    # Only applies to groups - users always reload via separate check
+    # Skip reload if: members already loaded, or config disables it
+    def should_reload_members?(record)
+      return false unless group_resource?
+      return false if record.scim_users.loaded?
+
+      TwoPercent.config.include_members_in_patch_response
+    end
+
     # Build base query scope with optional filtering
     def build_query_scope
       base_scope = user_resource? ? model_class.all : model_class.where(resource_type: params[:resource_type])

data/app/models/two_percent/scim_group.rb

@@ -10,7 +10,7 @@ module TwoPercent
     has_many :scim_users, through: :scim_group_memberships
 
     validates :scim_id, presence: true, uniqueness: true
-    validates :external_id, presence: true
+    validates :external_id, presence: true, uniqueness: { scope: :resource_type }
     validates :display_name, presence: true
     validates :resource_type, presence: true
     validates :scim_data, presence: true
@@ -34,13 +34,21 @@ module TwoPercent
       scim_hash = scim_hash.dup
       scim_hash["id"] ||= SecureRandom.uuid
 
+      # Extract members before validation to prevent storage in scim_data JSONB
+      members = scim_hash.delete("members")
+
       validated_data = TwoPercent::Scim::Schema.validate_group(scim_hash, require_id: true)
-      scim_group = find_or_initialize_by(scim_id: scim_hash["id"])
-      scim_group.update_from_scim!(resource_type, validated_data, correlation_id: correlation_id)
 
-      scim_group.replace_members(scim_hash["members"]) if scim_hash.key?("members")
+      # Wrap in transaction to ensure rollback on member validation failure
+      transaction do
+        scim_group = find_or_initialize_by(scim_id: scim_hash["id"])
+        scim_group.update_from_scim!(resource_type, validated_data, correlation_id: correlation_id)
+
+        # Sync members to join table only (never stored in scim_data)
+        scim_group.replace_members(members) if members
 
-      scim_group
+        scim_group
+      end
     end
 
     def self.find_by_scim_id(scim_id)
@@ -58,6 +66,7 @@ module TwoPercent
     # Extracts domain attributes for publishing in domain events
     #
     # Returns key attributes for event payloads.
+    # Members are NOT included - consumers should query TwoPercent models directly for current state.
     # @return [Hash] Domain attributes
     def to_domain_attributes
       {
@@ -103,15 +112,21 @@ module TwoPercent
 
     def replace_members(members_array)
       member_scim_ids = members_array.filter_map { |m| m["value"] }
-      existing_users = validate_users_exist!(member_scim_ids)
-      existing_user_ids = scim_group_memberships.pluck(:scim_user_id)
 
-      users_to_add = existing_users.where.not(id: existing_user_ids)
-      bulk_insert_memberships(users_to_add) if users_to_add.any?
+      # Get current member scim_ids efficiently (just IDs, no full records)
+      current_member_scim_ids = scim_group_memberships
+                                .joins(:scim_user)
+                                .pluck("two_percent_scim_users.scim_id")
+
+      # Calculate diff in Ruby (cheap for ID arrays)
+      scim_ids_to_add = member_scim_ids - current_member_scim_ids
+      scim_ids_to_remove = current_member_scim_ids - member_scim_ids
 
-      # Bulk delete removed memberships
-      users_to_remove_ids = scim_users.where.not(scim_id: member_scim_ids).pluck(:id)
-      scim_group_memberships.where(scim_user_id: users_to_remove_ids).delete_all
+      # Only validate and add NEW members (not existing ones)
+      add_members_by_scim_id(scim_ids_to_add) if scim_ids_to_add.any?
+
+      # Only remove members that need removing
+      remove_members_by_scim_id(scim_ids_to_remove) if scim_ids_to_remove.any?
     end
 
     # Extracts a nested attribute from the scim_data JSON
@@ -125,30 +140,80 @@ module TwoPercent
       scim_data.dig(*keys)
     end
 
+    # Build SCIM members representation from join table
+    # Optimized to bypass ActiveRecord and load only needed columns
+    #
+    # @return [Array<Hash>] Array of member references
+    def members_representation
+      scim_group_memberships
+        .joins(:scim_user)
+        .pluck("two_percent_scim_users.scim_id", "two_percent_scim_users.display_name")
+        .map do |scim_id, display_name|
+          {
+            "value" => scim_id,
+            "display" => display_name,
+            "$ref" => "Users/#{scim_id}",
+          }
+        end
+    end
+
+    # Build members array with value field only (for PatchProcessor)
+    # Uses pluck to avoid loading full AR objects
+    #
+    # @return [Array<Hash>] Array of member values
+    def members_for_patch
+      scim_group_memberships
+        .joins(:scim_user)
+        .pluck("two_percent_scim_users.scim_id")
+        .map { |id| { "value" => id } }
+    end
+
   private
 
-    # Validates that all user IDs exist in the database
+    # Add members by SCIM IDs, validating they exist
+    #
+    # @param scim_ids_to_add [Array<String>] SCIM IDs of users to add
+    def add_members_by_scim_id(scim_ids_to_add)
+      return if scim_ids_to_add.empty?
+
+      users_to_add = validate_and_fetch_users(scim_ids_to_add)
+      bulk_insert_new_memberships(users_to_add)
+    end
+
+    # Remove members by SCIM IDs (direct, no JOIN needed)
     #
-    # @param member_scim_ids [Array<String>] Array of SCIM user IDs to validate
+    # @param scim_ids_to_remove [Array<String>] SCIM IDs of users to remove
+    def remove_members_by_scim_id(scim_ids_to_remove)
+      return if scim_ids_to_remove.empty?
+
+      # Direct delete using SCIM IDs via subquery
+      scim_group_memberships
+        .where(scim_user_id: TwoPercent::ScimUser.where(scim_id: scim_ids_to_remove).select(:id))
+        .delete_all
+    end
+
+    # Validate users exist and return them
+    #
+    # @param scim_ids [Array<String>] SCIM IDs to validate
     # @return [ActiveRecord::Relation] The existing users
     # @raise [ArgumentError] If any users do not exist
-    def validate_users_exist!(member_scim_ids)
-      existing_users = TwoPercent::ScimUser.where(scim_id: member_scim_ids)
-      missing_ids = member_scim_ids - existing_users.pluck(:scim_id)
+    def validate_and_fetch_users(scim_ids)
+      users = TwoPercent::ScimUser.where(scim_id: scim_ids)
+      missing_ids = scim_ids - users.pluck(:scim_id)
 
       if missing_ids.any?
         raise ArgumentError,
               "Cannot add non-existent users to group: #{missing_ids.join(', ')}"
       end
 
-      existing_users
+      users
     end
 
-    # Bulk insert memberships for performance
+    # Bulk insert memberships for the given users
     #
-    # @param users_to_add [ActiveRecord::Relation] Users to add as members
-    def bulk_insert_memberships(users_to_add)
-      membership_records = users_to_add.pluck(:id).map do |user_id|
+    # @param users [ActiveRecord::Relation] Users to add as members
+    def bulk_insert_new_memberships(users)
+      membership_records = users.pluck(:id).map do |user_id|
         {
           scim_user_id: user_id,
           scim_group_id: id,
@@ -157,24 +222,10 @@ module TwoPercent
         }
       end
 
-      # Skip duplicates (handles race conditions and migration scenarios)
       TwoPercent::ScimGroupMembership.insert_all(
         membership_records,
         unique_by: %i[scim_user_id scim_group_id]
       )
     end
-
-    # Build SCIM members representation
-    #
-    # @return [Array<Hash>] Array of member references
-    def members_representation
-      scim_users.map do |user|
-        {
-          "value" => user.scim_id,
-          "display" => user.display_name,
-          "$ref" => "Users/#{user.scim_id}",
-        }
-      end
-    end
   end
 end

data/app/models/two_percent/scim_user.rb

@@ -10,7 +10,7 @@ module TwoPercent
     has_many :scim_groups, through: :scim_group_memberships
 
     validates :scim_id, presence: true, uniqueness: true
-    validates :external_id, presence: true
+    validates :external_id, presence: true, uniqueness: true
     validates :scim_data, presence: true
 
     scope :active, -> { where(active: true) }
@@ -30,9 +30,13 @@ module TwoPercent
       scim_hash = scim_hash.dup
       scim_hash["id"] ||= SecureRandom.uuid
 
+      # Extract groups before validation to prevent storage in scim_data JSONB
+      # Groups are synced to join table only (single source of truth)
+      groups = scim_hash.delete("groups")
+
       validated_data = TwoPercent::Scim::Schema.validate_user(scim_hash, require_id: true)
       scim_user = find_or_initialize_by(scim_id: scim_hash["id"])
-      scim_user.update_from_scim!(validated_data, correlation_id: correlation_id)
+      scim_user.update_from_scim!(validated_data, groups, correlation_id: correlation_id)
       scim_user
     end
 
@@ -50,29 +54,26 @@ module TwoPercent
 
     # Extracts domain attributes for publishing in domain events
     #
-    # Returns key attributes for event payloads.
-    # Includes associated group memberships if loaded.
+    # Returns key attributes for event payloads (thin events - no associations).
+    # Group memberships are queried separately by consumers who need them.
     #
     # @return [Hash] Domain attributes
     def to_domain_attributes
-      attributes = {
+      {
         scim_id: scim_id,
         external_id: external_id,
         user_name: user_name,
         display_name: display_name,
         email: email,
         active: active,
-      }
-
-      attributes[:groups] = group_memberships_attributes if scim_groups.loaded? || scim_groups.any?
-      attributes.compact
+      }.compact
     end
 
     # Returns full SCIM representation for HTTP responses
     #
     # @return [Hash] RFC 7644 compliant SCIM User resource
     def to_scim_representation
-      scim_data.merge(
+      representation = scim_data.merge(
         "id" => scim_id,
         "meta" => {
           "resourceType" => "User",
@@ -80,9 +81,41 @@ module TwoPercent
           "lastModified" => updated_at.iso8601,
         }
       )
+
+      # Build groups dynamically from join table (RFC 7643: User.groups is read-only)
+      # Single source of truth is join table - only included when association is loaded
+      representation["groups"] = groups_representation if scim_groups.loaded?
+
+      representation
     end
 
-    def update_from_scim!(validated_data, correlation_id: nil)
+    # Build SCIM groups representation dynamically from join table
+    # Per RFC 7643 Section 4.1.2, User.groups is read-only and must reflect Group memberships
+    #
+    # @return [Array<Hash>] Array of group references with SCIM-compliant attributes
+    def groups_representation
+      scim_groups.map do |group|
+        {
+          "value" => group.scim_id,
+          "display" => group.display_name,
+          "$ref" => "#{group.resource_type}/#{group.scim_id}",
+          "type" => group.resource_type,
+        }
+      end
+    end
+
+    # Updates user attributes from validated SCIM data
+    #
+    # NOTE: This method processes the User.groups array from the request payload
+    # and syncs group memberships, which is a deviation from strict RFC 7643 compliance
+    # (User.groups is specified as read-only in Section 4.1.2). This behavior is
+    # intentionally maintained for compatibility with existing SCIM clients that rely
+    # on this functionality for bulk sync operations.
+    #
+    # @param validated_data [Hash] Validated SCIM data with :core and :extensions keys
+    # @param groups_data [Array<Hash>, nil] Groups array extracted before validation
+    # @param correlation_id [String, nil] Optional correlation ID for tracking
+    def update_from_scim!(validated_data, groups_data, correlation_id: nil)
       core_data = validated_data[:core]
       self.scim_data = core_data.merge(validated_data[:extensions])
       self.scim_id = core_data["id"]
@@ -93,11 +126,21 @@ module TwoPercent
       self.active = core_data.fetch("active", true)
       self.correlation_id = correlation_id
       save!
-      sync_groups(core_data["groups"]) if core_data["groups"]
+      # Sync groups to join table only (never stored in scim_data)
+      sync_groups(groups_data) if groups_data
     end
 
+    # Syncs user's group memberships from SCIM groups array
+    #
+    # Accepts a groups array from SCIM User payload and updates associations.
+    # This enables bulk sync operations where clients send User.groups arrays.
+    #
+    # @param groups_data [Array<Hash>] Array of group references with "value" (scim_id)
+    # @example
+    #   sync_groups([{"value" => "group-123", "display" => "Engineering"}])
+    #   sync_groups([]) # Clears all group memberships
     def sync_groups(groups_data)
-      return if groups_data.blank?
+      return if groups_data.nil?
 
       group_ids = groups_data.filter_map { |g| g["value"] }
       groups = TwoPercent::ScimGroup.where(scim_id: group_ids)

data/lib/generators/two_percent/install/install_generator.rb

@@ -18,28 +18,56 @@ module TwoPercent
       end
 
       def copy_migrations
+        copy_users_migration
+        copy_groups_migration
+        copy_memberships_migration
+        copy_users_index_migration
+        copy_groups_index_migration
+      end
+
+      def copy_initializer
+        template "two_percent.rb.erb", "config/initializers/two_percent.rb"
+      end
+
+      def show_readme
+        readme "INSTALL_README" if behavior == :invoke
+      end
+
+    private
+
+      def copy_users_migration
         migration_template(
           "create_two_percent_scim_users.rb.erb",
           "db/migrate/create_two_percent_scim_users.rb"
         )
+      end
 
+      def copy_groups_migration
         migration_template(
           "create_two_percent_scim_groups.rb.erb",
           "db/migrate/create_two_percent_scim_groups.rb"
         )
+      end
 
+      def copy_memberships_migration
         migration_template(
           "create_two_percent_scim_group_memberships.rb.erb",
           "db/migrate/create_two_percent_scim_group_memberships.rb"
         )
       end
 
-      def copy_initializer
-        template "two_percent.rb.erb", "config/initializers/two_percent.rb"
+      def copy_users_index_migration
+        migration_template(
+          "add_unique_index_to_scim_users_external_id.rb.erb",
+          "db/migrate/add_unique_index_to_scim_users_external_id.rb"
+        )
       end
 
-      def show_readme
-        readme "INSTALL_README" if behavior == :invoke
+      def copy_groups_index_migration
+        migration_template(
+          "add_unique_composite_index_to_scim_groups.rb.erb",
+          "db/migrate/add_unique_composite_index_to_scim_groups.rb"
+        )
       end
     end
   end

data/lib/generators/two_percent/install/templates/add_unique_composite_index_to_scim_groups.rb.erb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class AddUniqueCompositeIndexToScimGroups < ActiveRecord::Migration[7.0]
+  def change
+    add_index :two_percent_scim_groups,
+              [:resource_type, :external_id],
+              unique: true,
+              name: "index_scim_groups_on_resource_and_external_id",
+              if_not_exists: true
+  end
+end

data/lib/generators/two_percent/install/templates/add_unique_index_to_scim_users_external_id.rb.erb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddUniqueIndexToScimUsersExternalId < ActiveRecord::Migration[7.0]
+  def change
+    add_index :two_percent_scim_users, :external_id, unique: true, if_not_exists: true
+  end
+end

data/lib/two_percent/bulk_processor.rb

@@ -2,8 +2,10 @@
 
 module TwoPercent
   class BulkProcessor
+    include TwoPercent::ValidatesUserGroupsPatch
+
     def initialize(operations, correlation_id: nil)
-      @operations = operations
+      @operations = operations.map(&:with_indifferent_access)
       @correlation_id = correlation_id
     end
 
@@ -50,39 +52,25 @@ module TwoPercent
     end
 
     def persist_create(resource_type, data)
-      if resource_type == "Users"
-        TwoPercent::ScimUser.upsert_from_scim(data, correlation_id: @correlation_id)
-      else
-        TwoPercent::ScimGroup.upsert_from_scim(resource_type, data, correlation_id: @correlation_id)
-      end
+      upsert_record(resource_type, data)
     end
 
     def persist_patch(resource_type, id, data)
-      # PATCH - apply operations to existing resource
       record = find_record(resource_type, id)
+      validate_patch_operations!(resource_type, data) if resource_type == "Users"
+
+      current_scim_data = prepare_scim_data_for_patch(record, resource_type)
 
-      # Apply SCIM PATCH operations (RFC 7644 compliance)
       processor = TwoPercent::Scim::PatchProcessor.new(data)
-      current_scim_data = record.scim_data || {}
       patched_data = processor.apply_to_hash(current_scim_data)
+      patched_data["id"] = id
 
-      # Persist patched data
-      patched_data["id"] = id # Ensure ID is present
-      if resource_type == "Users"
-        TwoPercent::ScimUser.upsert_from_scim(patched_data, correlation_id: @correlation_id)
-      else
-        TwoPercent::ScimGroup.upsert_from_scim(resource_type, patched_data, correlation_id: @correlation_id)
-      end
+      upsert_record(resource_type, patched_data)
     end
 
     def persist_update(resource_type, id, data)
-      # PUT - replace entire resource
       data_with_id = data.merge("id" => id)
-      if resource_type == "Users"
-        TwoPercent::ScimUser.upsert_from_scim(data_with_id, correlation_id: @correlation_id)
-      else
-        TwoPercent::ScimGroup.upsert_from_scim(resource_type, data_with_id, correlation_id: @correlation_id)
-      end
+      upsert_record(resource_type, data_with_id)
     end
 
     def persist_delete(resource_type, id)
@@ -149,6 +137,26 @@ module TwoPercent
       end
     end
 
+    def prepare_scim_data_for_patch(record, resource_type)
+      current_scim_data = record.scim_data || {}
+      return current_scim_data if resource_type == "Users"
+
+      # Sync scim_data["members"] from join table for Groups to ensure data consistency
+      # Must happen BEFORE PatchProcessor reads scim_data to ensure PATCH operations
+      # are applied to current members, not stale/empty data
+
+      current_scim_data["members"] = record.members_for_patch
+      current_scim_data
+    end
+
+    def upsert_record(resource_type, data)
+      if resource_type == "Users"
+        TwoPercent::ScimUser.upsert_from_scim(data, correlation_id: @correlation_id)
+      else
+        TwoPercent::ScimGroup.upsert_from_scim(resource_type, data, correlation_id: @correlation_id)
+      end
+    end
+
     def find_record(resource_type, scim_id)
       record =
         if resource_type == "Users"

data/lib/two_percent/configuration.rb

@@ -86,5 +86,21 @@ module TwoPercent
   #
   config_accessor :correlation_id_header, default: "X-Correlation-Id"
 
+  #
+  # Performance optimization: Skip members in Group PATCH responses
+  # RFC 7644 compliance (PATCH responses SHOULD return full resource)
+  #
+  # For Groups with large member lists, loading members can impact performance.
+  # Set to false to skip member loading in Group PATCH responses only:
+  #
+  #   TwoPercent.configure do |config|
+  #     config.include_members_in_patch_response = false
+  #   end
+  #
+  # User PATCH responses always include groups. GET requests always include
+  # members/groups regardless of this setting.
+  #
+  config_accessor :include_members_in_patch_response, default: true
+
   class ConfigurationError < StandardError; end
 end

data/lib/two_percent/scim/patch_processor.rb

@@ -21,7 +21,7 @@ module TwoPercent
           when "replace"
             apply_replace(result, operation[:path], operation[:value])
           when "remove"
-            apply_remove(result, operation[:path])
+            apply_remove(result, operation[:path], operation[:value])
           else
             raise ArgumentError, "Unknown PATCH operation: #{operation[:op]}"
           end
@@ -90,17 +90,26 @@ module TwoPercent
         end
       end
 
-      def apply_remove(hash, path)
+      def apply_remove(hash, path, value = nil)
         return if path.nil? || path.empty?
 
         keys = path.split(".")
         target = navigate_to_parent(hash, keys[0..-2])
         last_key = keys.last
 
-        # Special handling for members array - set to empty array instead of deleting
-        # This ensures upsert_from_scim can sync memberships to empty state
+        # Special handling for members array on Group resources
         if last_key == "members"
-          target[last_key] = []
+          if value.nil? || (value.is_a?(Array) && value.empty?)
+            # No value or empty array means remove all
+            target[last_key] = []
+          elsif target[last_key].is_a?(Array)
+            # Value provided: remove specific items by filtering
+            values_to_remove = Array(value).filter_map { |v| v["value"] || v[:value] }
+            target[last_key] = target[last_key].reject do |item|
+              item_value = item["value"] || item[:value]
+              values_to_remove.include?(item_value)
+            end
+          end
         else
           target.delete(last_key)
         end

data/lib/two_percent/validates_user_groups_patch.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  # Validates PATCH operations against RFC 7643 read-only attributes
+  #
+  # Ensures User.groups attribute cannot be modified via PATCH operations,
+  # as per RFC 7643 Section 4.1.2. Group memberships must be managed via
+  # PATCH operations on the Group resource itself.
+  module ValidatesUserGroupsPatch
+    # Validate PATCH operations against RFC 7643 read-only attributes
+    # @param resource_type [String] The SCIM resource type (e.g., "Users", "Groups")
+    # @param patch_request [Hash] The PATCH request payload
+    # @raise [TwoPercent::ReadOnlyAttributeError] if attempting to modify read-only User.groups
+    def validate_patch_operations!(resource_type, patch_request)
+      return unless resource_type == "Users"
+
+      patch_request = patch_request.with_indifferent_access
+      operations = patch_request[:Operations]
+      return unless operations.is_a?(Array)
+
+      operations.each { |operation| validate_operation_path!(operation.with_indifferent_access) }
+    end
+
+  private
+
+    # Validate a single PATCH operation path for read-only attributes
+    # @param operation [Hash] A single PATCH operation
+    # @raise [TwoPercent::ReadOnlyAttributeError] if attempting to modify User.groups
+    def validate_operation_path!(operation)
+      path = operation[:path]
+      value = operation[:value]
+
+      # Check path-based operations (e.g., {op: "add", path: "groups", value: [...]})
+      if path
+        base_path = path.split(/[.\[]/).first
+        raise_groups_read_only_error if base_path == "groups"
+      end
+
+      # Check pathless operations (e.g., {op: "replace", value: {active: true, groups: [...]}})
+      return unless value.is_a?(Hash)
+
+      value = value.with_indifferent_access
+      raise_groups_read_only_error if value[:groups]
+    end
+
+    def raise_groups_read_only_error
+      # RFC 7643 Section 4.1.2: User.groups is read-only
+      # RFC 7644 Section 3.5.2: Return 400 with scimType="mutability"
+      raise TwoPercent::ReadOnlyAttributeError,
+            "Attribute 'groups' is read-only per SCIM RFC 7643. Manage group membership via PATCH /scim/Groups/{id}"
+    end
+  end
+end

data/lib/two_percent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TwoPercent
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/two_percent.rb

@@ -5,11 +5,14 @@ require "aether_observatory"
 require "two_percent/version"
 require "two_percent/configuration"
 require "two_percent/domain"
+require "two_percent/validates_user_groups_patch"
 require "two_percent/bulk_processor"
 require "two_percent/scim"
 require "two_percent/syncable"
-
 module TwoPercent
+  # Custom exception for SCIM RFC 7643 read-only attribute violations
+  class ReadOnlyAttributeError < StandardError; end
+
   # Logger used by TwoPercent. Defaults to Rails.logger
   def self.logger
     config.logger || Rails.logger

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: two_percent
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Carlos Palhares
@@ -63,6 +63,8 @@ files:
 - config/routes.rb
 - lib/generators/two_percent/install/install_generator.rb
 - lib/generators/two_percent/install/templates/INSTALL_README
+- lib/generators/two_percent/install/templates/add_unique_composite_index_to_scim_groups.rb.erb
+- lib/generators/two_percent/install/templates/add_unique_index_to_scim_users_external_id.rb.erb
 - lib/generators/two_percent/install/templates/create_two_percent_scim_group_memberships.rb.erb
 - lib/generators/two_percent/install/templates/create_two_percent_scim_groups.rb.erb
 - lib/generators/two_percent/install/templates/create_two_percent_scim_users.rb.erb
@@ -81,6 +83,7 @@ files:
 - lib/two_percent/scim/patch_processor.rb
 - lib/two_percent/scim/schema.rb
 - lib/two_percent/syncable.rb
+- lib/two_percent/validates_user_groups_patch.rb
 - lib/two_percent/version.rb
 homepage: https://github.com/powerhome/power-tools
 licenses: