two_percent 0.5.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 533e741957e0c547a769287f8916a72005c839c7db3af317984caf541263bf15
-  data.tar.gz: 2b43afab484a19828f373069addae52cdabc3150434f267ff488454a566de4c3
+  metadata.gz: add03c75e1bf340f38e607daf123b473aec2f2b87b5785dd5a0c0c4b5c29ff6f
+  data.tar.gz: f3dda93ee923b646d652be8882db284fa2df08187fe5516c9f57ff2e5a85ebbf
 SHA512:
-  metadata.gz: debd817addfe72f031540b9d14a420bd0f9845880f61e5ed77d0cc31c36650362c725281d5629b5b514d39f9634a98cb35253de85b1d8d55eb21d79e6ccd420f
-  data.tar.gz: 8a0dc3faf0d6a4f1d02b1eb612bc37b693ab1ad2d3bf785c4ddf247acae55d78c7d4c3e506cf6b6b788136fbfab70510be47649f583e55cbc8ab42d9aeeac3a3
+  metadata.gz: 4bccbd154aee0eb6cde90ab96efd4eb685f33b4f2a04f304b5e7aef64cc9750641820bf99c2e650fd83c462238dd022d4c9afbfc93bbeb57b9c1dd9a9c947122
+  data.tar.gz: 4fe6f68630610ea02f86e48b0265c9e3ddc6b6f0f7636ca0fedd961904760b72842d6410dd759ff17ed776d424f8de7120feeb4a009b94004da5f2a670d0a463

data/Rakefile

@@ -5,9 +5,13 @@ require "bundler/setup"
 require "bundler/gem_tasks"
 
 require "rspec/core/rake_task"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
 RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
 RuboCop::RakeTask.new(:rubocop)
 
-task default: %i[rubocop spec]
+task default: %i[rubocop app:db:prepare spec]

data/app/controllers/two_percent/application_controller.rb

@@ -3,9 +3,87 @@
 module TwoPercent
   class ApplicationController < ActionController::API
     before_action :authenticate
+    before_action :extract_correlation_id
+
+    rescue_from ActiveRecord::RecordNotFound, with: :handle_record_not_found
+    rescue_from ActiveRecord::RecordInvalid, with: :handle_validation_error
+    rescue_from ArgumentError, with: :handle_bad_request
 
     def authenticate
-      instance_exec(&TwoPercent.config.authenticate)
+      result = instance_exec(&TwoPercent.config.authenticate)
+
+      return if result
+
+      render_scim_error(
+        status: :unauthorized,
+        scim_type: nil, # RFC 7644: No scimType for 401
+        detail: "Authentication failed"
+      )
+    end
+
+  private
+
+    def handle_record_not_found(exception)
+      # RFC 7644: Error Response with scimType
+      render_scim_error(
+        status: :not_found,
+        scim_type: "noTarget",
+        detail: exception.message
+      )
+    end
+
+    def handle_validation_error(exception)
+      # RFC 7644: 400 Bad Request for invalid data
+      scim_type = exception.message.match?(/uniqueness|unique/i) ? "uniqueness" : "invalidValue"
+
+      render_scim_error(
+        status: :bad_request,
+        scim_type: scim_type,
+        detail: exception.message
+      )
+    end
+
+    def handle_bad_request(exception)
+      # RFC 7644: 400 Bad Request for malformed requests
+      scim_type = exception.message.match?(/schemas/i) ? "invalidValue" : "invalidSyntax"
+
+      render_scim_error(
+        status: :bad_request,
+        scim_type: scim_type,
+        detail: exception.message
+      )
+    end
+
+    def extract_correlation_id
+      header_name = TwoPercent.config.correlation_id_header
+      @correlation_id = request.headers[header_name] || SecureRandom.uuid
+    end
+
+    # RFC 7644 Section 3.12: SCIM Error Response Format
+    #
+    # scimType values:
+    # - invalidFilter: The specified filter syntax was invalid
+    # - tooMany: The specified filter yields many more results than the server is willing to calculate
+    # - uniqueness: One or more of the attribute values are already in use or are reserved
+    # - mutability: The attempted modification is not compatible with the target attribute's mutability
+    # - invalidSyntax: The request body message structure was invalid or did not conform to the request schema
+    # - invalidPath: The "path" attribute was invalid or malformed
+    # - noTarget: The specified "path" did not yield an attribute or attribute value that could be operated on (404)
+    # - invalidValue: A required value was missing, or the value specified was not compatible with the operation
+    # - invalidVers: The specified SCIM protocol version is not supported
+    # - sensitive: The specified request cannot be completed due to the passing of sensitive information
+    #
+    def render_scim_error(status:, scim_type:, detail:)
+      error_response = {
+        schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+        status: Rack::Utils::SYMBOL_TO_STATUS_CODE[status].to_s,
+        detail: detail,
+      }
+
+      # RFC 7644: scimType is optional, only include if provided
+      error_response[:scimType] = scim_type if scim_type
+
+      render json: error_response, status: status
     end
   end
 end

data/app/controllers/two_percent/bulk_controller.rb

@@ -2,16 +2,32 @@
 
 module TwoPercent
   class BulkController < ApplicationController
-    def _dispatch = processor.dispatch
+    def _dispatch
+      log_bulk_operation("start")
+      processor.dispatch
+      log_bulk_operation("complete")
+    end
 
   private
 
     def processor
-      @processor ||= TwoPercent::BulkProcessor.new(operations)
+      @processor ||= TwoPercent::BulkProcessor.new(operations, correlation_id: @correlation_id)
     end
 
     def operations
       params.require(:Operations).map { _1.permit(:method, :path, :bulkId, data: {}).to_h }
     end
+
+    def log_bulk_operation(stage)
+      log_data = {
+        correlation_id: @correlation_id,
+        operation: "bulk",
+        operation_count: operations.size,
+        stage: stage,
+        service: "two_percent",
+      }
+
+      Rails.logger.info(log_data.to_json)
+    end
   end
 end

data/app/controllers/two_percent/scim_controller.rb

@@ -3,27 +3,135 @@
 module TwoPercent
   class ScimController < ApplicationController
     def create
-      TwoPercent::CreateEvent.create(resource: params[:resource_type], params: scim_params)
+      record = with_scim_logging("create") do
+        # Persist to two_percent tables first (validates SCIM schema)
+        record = persist_scim_record(scim_params)
 
-      head :ok
+        # Reload with associations for domain event and response
+        record = reload_with_members(record)
+
+        # Publish domain event (not SCIM-specific)
+        publish_created_event(record)
+
+        record
+      end
+
+      # RFC 7644: 201 Created with Location header and resource body
+      render json: record.to_scim_representation, status: :created, location: scim_resource_url(record)
     end
 
     def update
-      TwoPercent::UpdateEvent.create(resource: params[:resource_type], id: params[:id], params: scim_params)
+      record = with_scim_logging("update") do
+        # Find existing record
+        record = find_scim_record(params[:id])
+
+        # Apply SCIM PATCH operations (RFC 7644 compliance)
+        processor = TwoPercent::Scim::PatchProcessor.new(scim_params)
+        current_scim_data = record.scim_data || {}
+        patched_data = processor.apply_to_hash(current_scim_data)
+
+        # Persist patched data
+        patched_data["id"] = params[:id] # Ensure ID is present
+        updated_record = persist_scim_record(patched_data)
 
-      head :ok
+        # Reload with associations for domain event and response
+        updated_record = reload_with_members(updated_record)
+
+        # Publish domain event with final state
+        publish_updated_event(updated_record)
+
+        updated_record
+      end
+
+      # RFC 7644: 200 OK with updated resource body
+      render json: record.to_scim_representation, status: :ok
     end
 
     def replace
-      TwoPercent::ReplaceEvent.create(resource: params[:resource_type], id: params[:id], params: scim_params)
+      # Upsert record (create or replace)
+      was_new = !model_class.exists_by_scim_id?(params[:id])
+
+      record = with_scim_logging("replace") do
+        record = upsert_scim_record(params[:id], scim_params)
+
+        # Reload with associations for domain event and response
+        record = reload_with_members(record)
 
-      head :ok
+        # Publish appropriate domain event
+        if was_new
+          publish_created_event(record)
+        else
+          publish_updated_event(record)
+        end
+
+        record
+      end
+
+      # RFC 7644: 201 Created (if new) or 200 OK (if replaced)
+      if was_new
+        render json: record.to_scim_representation, status: :created, location: scim_resource_url(record)
+      else
+        render json: record.to_scim_representation, status: :ok
+      end
     end
 
     def destroy
-      TwoPercent::DeleteEvent.create(resource: params[:resource_type], id: params[:id])
+      scim_id = with_scim_logging("delete") do
+        # Find and destroy record
+        record = find_scim_record(params[:id])
+        scim_id = record.scim_id
+
+        # Destroy record
+        model_class.destroy_by_scim_id(scim_id)
+
+        # Publish domain delete event
+        publish_deleted_event(scim_id)
+
+        scim_id
+      end
+
+      # RFC 7644: 204 No Content
+      head :no_content
+    end
+
+    def show
+      validate_resource_type!
+
+      record = with_scim_logging("get") do
+        # Find record (raises RecordNotFound if not exists)
+        record = find_scim_record(params[:id])
 
-      head :ok
+        # Reload with associations for complete SCIM representation
+        reload_with_members(record)
+      end
+
+      # RFC 7644: 200 OK with resource body (no domain events for read operations)
+      render json: record.to_scim_representation, status: :ok
+    end
+
+    def index
+      validate_resource_type!
+      log_scim_operation("list", "start")
+
+      # Build base query scope
+      scope = build_query_scope
+
+      # Get total count before pagination
+      total_count = scope.count
+
+      # Apply pagination
+      paginated_scope = apply_pagination(scope)
+
+      # Load records with associations
+      records = load_records_with_associations(paginated_scope)
+
+      # Build RFC 7644 ListResponse
+      list_response = build_list_response(records, total_count)
+
+      log_scim_operation("list", "complete")
+
+      # RFC 7644: 200 OK with ListResponse (no domain events for read operations)
+      render json: list_response, status: :ok
     end
 
   private
@@ -31,5 +139,178 @@ module TwoPercent
     def scim_params
       params.except(:controller, :action, :resource_type).as_json.with_indifferent_access
     end
+
+    def user_resource?
+      params[:resource_type] == "Users"
+    end
+
+    def group_resource?
+      TwoPercent.config.group_resource_types.include?(params[:resource_type])
+    end
+
+    def validate_resource_type!
+      return if user_resource? || group_resource?
+
+      raise ArgumentError, "Unknown resource type: #{params[:resource_type]}"
+    end
+
+    def persist_scim_record(scim_hash)
+      if user_resource?
+        TwoPercent::ScimUser.upsert_from_scim(scim_hash, correlation_id: @correlation_id)
+      elsif group_resource?
+        TwoPercent::ScimGroup.upsert_from_scim(params[:resource_type], scim_hash, correlation_id: @correlation_id)
+      else
+        raise ArgumentError, "Unknown resource type: #{params[:resource_type]}"
+      end
+    end
+
+    def find_scim_record(scim_id)
+      record = model_class.find_by_scim_id(scim_id)
+      raise ActiveRecord::RecordNotFound, "Resource \"#{scim_id}\" not found" unless record
+
+      record
+    end
+
+    def upsert_scim_record(scim_id, scim_hash)
+      # Ensure scim_id is in the hash
+      scim_hash_with_id = scim_hash.merge("id" => scim_id)
+      persist_scim_record(scim_hash_with_id)
+    end
+
+    def with_scim_logging(operation)
+      log_scim_operation(operation, "start", params[:id])
+      record = yield
+      scim_id = record.respond_to?(:scim_id) ? record.scim_id : record
+      log_scim_operation(operation, "complete", scim_id || params[:id])
+      record
+    end
+
+    def log_scim_operation(operation, stage, scim_id = nil)
+      log_data = {
+        correlation_id: @correlation_id,
+        operation: operation,
+        resource_type: params[:resource_type],
+        stage: stage,
+        service: "two_percent",
+      }
+      log_data[:scim_id] = scim_id if scim_id
+
+      Rails.logger.info(log_data.to_json)
+    end
+
+    # Domain event publishers
+    def publish_created_event(record)
+      if user_resource?
+        TwoPercent::Domain::Events::UserCreated.create(
+          user_attributes: record.to_domain_attributes,
+          correlation_id: @correlation_id
+        )
+      else
+        TwoPercent::Domain::Events::GroupCreated.create(
+          group_attributes: record.to_domain_attributes,
+          resource_type: params[:resource_type],
+          correlation_id: @correlation_id
+        )
+      end
+    end
+
+    def publish_updated_event(record)
+      if user_resource?
+        TwoPercent::Domain::Events::UserUpdated.create(
+          user_attributes: record.to_domain_attributes,
+          correlation_id: @correlation_id
+        )
+      else
+        TwoPercent::Domain::Events::GroupUpdated.create(
+          group_attributes: record.to_domain_attributes,
+          resource_type: params[:resource_type],
+          correlation_id: @correlation_id
+        )
+      end
+    end
+
+    def publish_deleted_event(scim_id)
+      if user_resource?
+        TwoPercent::Domain::Events::UserDeleted.create(
+          user_id: scim_id,
+          correlation_id: @correlation_id
+        )
+      else
+        TwoPercent::Domain::Events::GroupDeleted.create(
+          group_id: scim_id,
+          resource_type: params[:resource_type],
+          correlation_id: @correlation_id
+        )
+      end
+    end
+
+    # Generate SCIM resource URL for Location header (RFC 7644)
+    def scim_resource_url(record)
+      resource_type = user_resource? ? "Users" : params[:resource_type]
+      "#{request.base_url}/scim/#{resource_type}/#{record.scim_id}"
+    end
+
+    # Reload record with associations (users load groups, groups load members)
+    def reload_with_members(record)
+      model_class.includes(association_name).find(record.id)
+    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])
+
+      # Apply query filtering if present
+      scope = if params[:query].present?
+                # Sanitize LIKE wildcards (%, _, \) before interpolating into pattern
+                sanitized_query = ActiveRecord::Base.sanitize_sql_like(params[:query])
+                base_scope.where("LOWER(display_name) LIKE LOWER(?) ESCAPE '\\'", "%#{sanitized_query}%")
+              else
+                base_scope
+              end
+
+      # Order by id for deterministic pagination results
+      # Without ORDER BY, paginated results are non-deterministic and can return duplicates/skip records
+      scope.order(:id)
+    end
+
+    # Apply SCIM pagination (RFC 7644 uses 1-based indexing)
+    def apply_pagination(scope)
+      start_index = (params[:startIndex] || 1).to_i
+      count = (params[:count] || 100).to_i
+
+      # Enforce maximum count limit
+      count = [count, 1000].min
+
+      # Convert SCIM 1-based startIndex to 0-based offset
+      offset = [start_index - 1, 0].max
+
+      scope.offset(offset).limit(count)
+    end
+
+    # Load records with associations
+    def load_records_with_associations(scope)
+      scope.includes(association_name).to_a
+    end
+
+    # Build RFC 7644 ListResponse format
+    def build_list_response(records, total_count)
+      start_index = (params[:startIndex] || 1).to_i
+
+      {
+        schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
+        totalResults: total_count,
+        startIndex: start_index,
+        itemsPerPage: records.size,
+        Resources: records.map(&:to_scim_representation),
+      }
+    end
+
+    def model_class
+      user_resource? ? TwoPercent::ScimUser : TwoPercent::ScimGroup
+    end
+
+    def association_name
+      user_resource? ? :scim_groups : :scim_users
+    end
   end
 end

data/app/models/two_percent/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/two_percent/scim_group.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  class ScimGroup < ApplicationRecord
+    self.table_name = "two_percent_scim_groups"
+    serialize :scim_data, coder: JSON
+
+    has_many :scim_group_memberships, class_name: "TwoPercent::ScimGroupMembership",
+                                      foreign_key: :scim_group_id, dependent: :destroy
+    has_many :scim_users, through: :scim_group_memberships
+
+    validates :scim_id, presence: true, uniqueness: true
+    validates :external_id, presence: true
+    validates :display_name, presence: true
+    validates :resource_type, presence: true
+    validates :scim_data, presence: true
+
+    scope :active, -> { where(active: true) }
+    scope :by_resource_type, ->(type) { where(resource_type: type) }
+
+    # Creates or updates a group from SCIM data
+    #
+    # Generates a UUID for the id field if not present (for POST/create operations).
+    # Validates the SCIM data against the Group schema before persisting.
+    #
+    # @param resource_type [String] The resource type (e.g., "Groups", "Departments", "Territories")
+    # @param scim_hash [Hash] SCIM Group resource hash conforming to RFC 7643
+    # @param correlation_id [String, nil] Optional correlation ID for tracking
+    #   changes across network hops (e.g., App A -> App B -> App C)
+    # @return [TwoPercent::ScimGroup] The persisted group record
+    # @raise [TwoPercent::Scim::ValidationError] If SCIM data fails schema validation
+    def self.upsert_from_scim(resource_type, scim_hash, correlation_id: nil)
+      # Generate SCIM id (stored as scim_id) if not provided (typical for POST operations)
+      scim_hash = scim_hash.dup
+      scim_hash["id"] ||= SecureRandom.uuid
+
+      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"], correlation_id) if scim_hash.key?("members")
+
+      scim_group
+    end
+
+    def self.find_by_scim_id(scim_id)
+      find_by(scim_id: scim_id)
+    end
+
+    def self.exists_by_scim_id?(scim_id)
+      exists?(scim_id: scim_id)
+    end
+
+    def self.destroy_by_scim_id(scim_id)
+      find_by_scim_id(scim_id)&.destroy
+    end
+
+    # Extracts domain attributes for publishing in domain events
+    #
+    # Returns key attributes for event payloads.
+    # @return [Hash] Domain attributes
+    def to_domain_attributes
+      {
+        scim_id: scim_id,
+        external_id: external_id,
+        display_name: display_name,
+        resource_type: resource_type,
+        active: active,
+      }.compact
+    end
+
+    # Returns full SCIM representation for HTTP responses
+    #
+    # @return [Hash] RFC 7644 compliant SCIM Group resource
+    def to_scim_representation
+      representation = scim_data.merge(
+        "id" => scim_id,
+        "meta" => {
+          "resourceType" => resource_type,
+          "created" => created_at.iso8601,
+          "lastModified" => updated_at.iso8601,
+        }
+      )
+
+      representation["members"] = members_representation if scim_users.loaded?
+      representation
+    end
+
+    def update_from_scim!(resource_type, validated_data, correlation_id: nil)
+      core_data = validated_data[:core]
+      self.scim_data = core_data.merge(validated_data[:extensions])
+      self.scim_id = core_data["id"]
+      self.external_id = core_data["externalId"]
+      self.display_name = core_data["displayName"]
+      self.resource_type = resource_type
+
+      extension_data = validated_data[:extensions]
+      self.active = extension_data.dig("urn:ietf:params:scim:schemas:extension:authservice:2.0:Group",
+                                       "active") != false
+      self.correlation_id = correlation_id
+      save!
+    end
+
+    def replace_members(members_array, correlation_id)
+      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, correlation_id) if users_to_add.any?
+
+      # 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
+    end
+
+    # Extracts a nested attribute from the scim_data JSON
+    #
+    # @param path [String] Dot-separated path to the attribute (e.g., "displayName")
+    # @return [Object, nil] The attribute value or nil if not found
+    # @example
+    #   group.scim_attribute("members.0.value") # => "user-id-123"
+    def scim_attribute(path)
+      keys = path.split(".")
+      scim_data.dig(*keys)
+    end
+
+  private
+
+    # Validates that all user IDs exist in the database
+    #
+    # @param member_scim_ids [Array<String>] Array of SCIM user 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)
+
+      if missing_ids.any?
+        raise ArgumentError,
+              "Cannot add non-existent users to group: #{missing_ids.join(', ')}"
+      end
+
+      existing_users
+    end
+
+    # Bulk insert memberships for performance
+    #
+    # @param users_to_add [ActiveRecord::Relation] Users to add as members
+    # @param correlation_id [String, nil] Correlation ID for tracking
+    def bulk_insert_memberships(users_to_add, correlation_id)
+      membership_records = users_to_add.pluck(:id).map do |user_id|
+        {
+          scim_user_id: user_id,
+          scim_group_id: id,
+          correlation_id: correlation_id,
+          created_at: Time.current,
+          updated_at: Time.current,
+        }
+      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_group_membership.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  class ScimGroupMembership < ApplicationRecord
+    self.table_name = "two_percent_scim_group_memberships"
+
+    belongs_to :scim_user, class_name: "TwoPercent::ScimUser",
+                           foreign_key: :scim_user_id
+    belongs_to :scim_group, class_name: "TwoPercent::ScimGroup",
+                            foreign_key: :scim_group_id
+
+    validates :scim_user_id, presence: true
+    validates :scim_group_id, presence: true
+    validates :scim_user_id, uniqueness: { scope: :scim_group_id, message: "already a member of this group" }
+
+    def self.find_or_create_membership(scim_user:, scim_group:, correlation_id: nil)
+      find_or_create_by!(
+        scim_user_id: scim_user.id,
+        scim_group_id: scim_group.id
+      ) do |membership|
+        membership.correlation_id = correlation_id
+      end
+    end
+
+    def self.remove_membership(scim_user:, scim_group:)
+      find_by(scim_user_id: scim_user.id, scim_group_id: scim_group.id)&.destroy
+    end
+  end
+end