two_percent 0.5.0 → 1.0.0

data/app/models/two_percent/scim_user.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  class ScimUser < ApplicationRecord
+    self.table_name = "two_percent_scim_users"
+    serialize :scim_data, coder: JSON
+
+    has_many :scim_group_memberships, class_name: "TwoPercent::ScimGroupMembership",
+                                      foreign_key: :scim_user_id, dependent: :destroy
+    has_many :scim_groups, through: :scim_group_memberships
+
+    validates :scim_id, presence: true, uniqueness: true
+    validates :external_id, presence: true
+    validates :scim_data, presence: true
+
+    scope :active, -> { where(active: true) }
+
+    # Creates or updates a user from SCIM data
+    #
+    # Generates a UUID for the id field if not present (for POST/create operations).
+    # Validates the SCIM data against the User schema before persisting.
+    #
+    # @param scim_hash [Hash] SCIM User 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::ScimUser] The persisted user record
+    # @raise [TwoPercent::Scim::ValidationError] If SCIM data fails schema validation
+    def self.upsert_from_scim(scim_hash, correlation_id: nil)
+      # Generate ID if not present (for POST/create operations)
+      scim_hash = scim_hash.dup
+      scim_hash["id"] ||= SecureRandom.uuid
+
+      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
+    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.
+    # Includes associated group memberships if loaded.
+    #
+    # @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
+    end
+
+    # Returns full SCIM representation for HTTP responses
+    #
+    # @return [Hash] RFC 7644 compliant SCIM User resource
+    def to_scim_representation
+      scim_data.merge(
+        "id" => scim_id,
+        "meta" => {
+          "resourceType" => "User",
+          "created" => created_at.iso8601,
+          "lastModified" => updated_at.iso8601,
+        }
+      )
+    end
+
+    def update_from_scim!(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.user_name = core_data["userName"]
+      self.display_name = core_data["displayName"]
+      self.email = core_data.dig("emails", 0, "value")
+      self.active = core_data.fetch("active", true)
+      self.correlation_id = correlation_id
+      save!
+      sync_groups(core_data["groups"]) if core_data["groups"]
+    end
+
+    def sync_groups(groups_data)
+      return if groups_data.blank?
+
+      group_ids = groups_data.filter_map { |g| g["value"] }
+      groups = TwoPercent::ScimGroup.where(scim_id: group_ids)
+      self.scim_groups = groups
+    end
+
+    # Extracts a nested attribute from the scim_data JSON
+    #
+    # @param path [String] Dot-separated path to the attribute (e.g., "name.givenName")
+    # @return [Object, nil] The attribute value or nil if not found
+    # @example
+    #   user.scim_attribute("emails.0.value") # => "user@example.com"
+    def scim_attribute(path)
+      keys = path.split(".")
+      scim_data.dig(*keys)
+    end
+
+    def extension_attributes(schema_urn = nil)
+      if schema_urn
+        scim_data[schema_urn] || {}
+      else
+        scim_data.select { |k, _| k.start_with?("urn:ietf:params:scim:schemas:extension:") }
+      end
+    end
+
+  private
+
+    def group_memberships_attributes
+      scim_groups.map do |group|
+        {
+          scim_id: group.scim_id,
+          display_name: group.display_name,
+          resource_type: group.resource_type,
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module TwoPercent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs TwoPercent SCIM integration with migrations and initializer"
+
+      def self.next_migration_number(path)
+        ActiveRecord::Generators::Base.next_migration_number(path)
+      end
+
+      def copy_migrations
+        migration_template(
+          "create_two_percent_scim_users.rb.erb",
+          "db/migrate/create_two_percent_scim_users.rb"
+        )
+
+        migration_template(
+          "create_two_percent_scim_groups.rb.erb",
+          "db/migrate/create_two_percent_scim_groups.rb"
+        )
+
+        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"
+      end
+
+      def show_readme
+        readme "INSTALL_README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/two_percent/install/templates/INSTALL_README

@@ -0,0 +1,84 @@
+===============================================================================
+  TwoPercent SCIM Integration Installed Successfully!
+===============================================================================
+
+Next Steps:
+
+1. Run migrations to create SCIM tables:
+
+   rails db:migrate
+
+2. Configure authentication in config/initializers/two_percent.rb:
+
+   Replace the NotImplementedError with your authentication logic
+   (bearer token, BasicAuth, API key, etc.)
+
+3. Mount SCIM routes in config/routes.rb:
+
+   mount TwoPercent::Engine => "/scim"
+
+   Or mount at a custom path:
+   mount TwoPercent::Engine => "/api/scim/v2"
+
+4. Subscribe to domain events:
+
+   TwoPercent publishes domain events when SCIM resources change:
+
+   - TwoPercent::Domain::Events::UserCreated
+   - TwoPercent::Domain::Events::UserUpdated
+   - TwoPercent::Domain::Events::UserDeleted
+   - TwoPercent::Domain::Events::GroupCreated
+   - TwoPercent::Domain::Events::GroupUpdated
+   - TwoPercent::Domain::Events::GroupDeleted
+
+   Subscribe using ActiveSupport::Notifications or integrate using the
+   Syncable concern (see step 5)
+
+5. (Option A) Subscribe to events manually:
+
+   ActiveSupport::Notifications.subscribe(/TwoPercent::Domain::Events/) do |name, start, finish, id, payload|
+     event = payload[:event]
+     case event
+     when TwoPercent::Domain::Events::UserCreated
+       User.create!(scim_id: event.user_attributes[:scim_id], ...)
+     when TwoPercent::Domain::Events::UserUpdated
+       user = User.find_by(scim_id: event.user_attributes[:scim_id])
+       user&.update!(event.user_attributes.slice(...))
+     end
+   end
+
+6. (Option B) Use Syncable concern for automatic sync:
+
+   class User < ApplicationRecord
+     include TwoPercent::Syncable
+
+     syncable_as :user, scim_id_column: :scim_id do |scim_attrs|
+       {
+         first_name: scim_attrs.dig(:name, :givenName),
+         last_name: scim_attrs.dig(:name, :familyName),
+         email: scim_attrs[:email],
+         active: scim_attrs[:active]
+       }
+     end
+   end
+
+   Then subscribe to events:
+   ActiveSupport::Notifications.subscribe(/TwoPercent::Domain::Events/) do |name, start, finish, id, payload|
+     event = payload[:event]
+     User.sync_from_scim_event(event) if event.is_a?(TwoPercent::Domain::Events::Base)
+   end
+
+7. (Option C) Query SCIM models directly:
+
+   scim_user = TwoPercent::ScimUser.find_by_scim_id("user-123")
+   attrs = scim_user.to_domain_attributes
+   email = scim_user.scim_data["email"]
+
+===============================================================================
+
+For detailed documentation and examples, see:
+https://github.com/powerhome/power-tools/tree/main/packages/two_percent
+
+Questions or issues? Open an issue on GitHub.
+
+===============================================================================

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateTwoPercentScimGroupMemberships < ActiveRecord::Migration[7.0]
+  def change
+    create_table :two_percent_scim_group_memberships do |t|
+      t.integer :scim_user_id, null: false
+      t.integer :scim_group_id, null: false
+      t.string :correlation_id
+
+      t.timestamps
+
+      t.index :scim_user_id
+      t.index :scim_group_id
+      t.index [:scim_user_id, :scim_group_id], unique: true, name: "index_scim_memberships_on_user_and_group"
+      t.index :correlation_id
+    end
+
+    # Note: No explicit foreign keys for Percona/MySQL compatibility
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateTwoPercentScimGroups < ActiveRecord::Migration[7.0]
+  def change
+    create_table :two_percent_scim_groups do |t|
+      t.string :scim_id, null: false
+      t.string :external_id, null: false
+      t.string :display_name, null: false
+      t.string :resource_type, null: false
+      t.boolean :active, default: true
+      t.text :scim_data, limit: 16_777_215  # MEDIUMTEXT for MySQL
+      t.string :correlation_id
+
+      t.timestamps
+
+      t.index :scim_id, unique: true
+      t.index :external_id
+      t.index [:resource_type, :external_id], name: "index_scim_groups_on_resource_and_external_id"
+      t.index :resource_type
+      t.index :active
+      t.index :correlation_id
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class CreateTwoPercentScimUsers < ActiveRecord::Migration[7.0]
+  def change
+    create_table :two_percent_scim_users do |t|
+      t.string :scim_id, null: false
+      t.string :external_id, null: false
+      t.string :user_name
+      t.string :display_name
+      t.string :email
+      t.boolean :active, default: true
+      t.text :scim_data, limit: 16_777_215  # MEDIUMTEXT for MySQL
+      t.string :correlation_id
+
+      t.timestamps
+
+      t.index :scim_id, unique: true
+      t.index :external_id
+      t.index :user_name
+      t.index :email
+      t.index :active
+      t.index :correlation_id
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+Rails.application.config.to_prepare do
+  TwoPercent.configure do |config|
+    # ============================================================
+    # Authentication (Required)
+    # ============================================================
+    # Define how to authenticate SCIM requests
+    # This should return truthy value for authenticated requests
+    # 
+    # Example with bearer token:
+    #   config.authenticate = ->(request) do
+    #     token = request.headers["Authorization"]&.remove("Bearer ")
+    #     token == Rails.application.credentials.scim_token
+    #   end
+    #
+    # Example with BasicAuth:
+    #   config.authenticate = ->(request) do
+    #     ActionController::HttpAuthentication::Basic.authenticate(request) do |username, password|
+    #       username == "scim_user" && password == Rails.application.credentials.scim_password
+    #     end
+    #   end
+    #
+    config.authenticate = ->(request) do
+      # TODO: Implement your authentication logic here
+      # Return true for authenticated requests, false otherwise
+      raise NotImplementedError, "TwoPercent authentication not configured"
+    end
+
+    # ============================================================
+    # Integration with Your Application
+    # ============================================================
+    # TwoPercent publishes domain events when SCIM resources change.
+    # Choose your integration approach:
+    #
+    # Option 1: Subscribe to domain events (recommended)
+    #   ActiveSupport::Notifications.subscribe(/TwoPercent::Domain::Events/) do |name, start, finish, id, payload|
+    #     event = payload[:event]
+    #     case event
+    #     when TwoPercent::Domain::Events::UserCreated
+    #       User.create!(
+    #         scim_id: event.user_attributes[:scim_id],
+    #         email: event.user_attributes[:email],
+    #         first_name: event.user_attributes.dig(:name, :givenName)
+    #       )
+    #     when TwoPercent::Domain::Events::UserUpdated
+    #       user = User.find_by(scim_id: event.user_attributes[:scim_id])
+    #       user&.update!(email: event.user_attributes[:email])
+    #     end
+    #   end
+    #
+    # Option 2: Use the Syncable concern (declarative)
+    #   class User < ApplicationRecord
+    #     include TwoPercent::Syncable
+    #     
+    #     syncable_as :user, scim_id_column: :scim_id do |scim_attrs|
+    #       {
+    #         first_name: scim_attrs.dig(:name, :givenName),
+    #         last_name: scim_attrs.dig(:name, :familyName),
+    #         email: scim_attrs[:email],
+    #         active: scim_attrs[:active]
+    #       }
+    #     end
+    #   end
+    #   
+    #   # Then subscribe to events and sync automatically:
+    #   ActiveSupport::Notifications.subscribe(/TwoPercent::Domain::Events/) do |name, start, finish, id, payload|
+    #     event = payload[:event]
+    #     User.sync_from_scim_event(event) if event.is_a?(TwoPercent::Domain::Events::Base)
+    #   end
+    #
+    # Option 3: Query SCIM models directly
+    #   scim_user = TwoPercent::ScimUser.find_by_scim_id("user-123")
+    #   email = scim_user.scim_data["email"]
+    #   attrs = scim_user.to_domain_attributes
+    #
+    # Events published:
+    # - TwoPercent::Domain::Events::UserCreated
+    # - TwoPercent::Domain::Events::UserUpdated
+    # - TwoPercent::Domain::Events::UserDeleted
+    # - TwoPercent::Domain::Events::GroupCreated
+    # - TwoPercent::Domain::Events::GroupUpdated
+    # - TwoPercent::Domain::Events::GroupDeleted
+  end
+end

data/lib/two_percent/bulk_processor.rb

@@ -2,15 +2,26 @@
 
 module TwoPercent
   class BulkProcessor
-    def initialize(operations)
+    def initialize(operations, correlation_id: nil)
       @operations = operations
+      @correlation_id = correlation_id
     end
 
-    def dispatch(event_handler = EventHandler)
+    def dispatch
       @operations.each do |operation|
-        resource, id = parse_path(operation[:path])
-        attrs = { resource: resource, id: id, params: operation[:data] }.compact
-        event_handler.dispatch(operation[:method], **attrs)
+        resource_type, id = parse_path(operation[:path])
+
+        # Persist data to two_percent tables first (wrapped in transaction for bulk integrity)
+        ActiveRecord::Base.transaction do
+          record = persist_bulk_operation(operation[:method], resource_type, id, operation[:data])
+
+          # Publish domain events based on operation
+          # Note: DELETE operations don't return a record, but still need to publish events
+          if record || operation[:method] == "DELETE"
+            publish_domain_event(operation[:method], resource_type, record,
+                                 id)
+          end
+        end
       end
     end
 
@@ -21,5 +32,134 @@ module TwoPercent
 
       [resource_type, id]
     end
+
+    def persist_bulk_operation(method, resource_type, id, data)
+      case method
+      when "POST"
+        persist_create(resource_type, data)
+      when "PATCH"
+        persist_patch(resource_type, id, data)
+      when "PUT"
+        persist_update(resource_type, id, data)
+      when "DELETE"
+        persist_delete(resource_type, id)
+        nil # No record to return for deletes
+      else
+        raise ArgumentError, "Unknown HTTP method: #{method}"
+      end
+    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
+    end
+
+    def persist_patch(resource_type, id, data)
+      # PATCH - apply operations to existing resource
+      record = find_record(resource_type, id)
+
+      # 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)
+
+      # 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
+    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
+    end
+
+    def persist_delete(resource_type, id)
+      if resource_type == "Users"
+        TwoPercent::ScimUser.destroy_by_scim_id(id)
+      else
+        TwoPercent::ScimGroup.destroy_by_scim_id(id)
+      end
+    end
+
+    def publish_domain_event(method, resource_type, record, id)
+      case method
+      when "POST"
+        publish_created_event(resource_type, record)
+      when "PATCH", "PUT"
+        publish_updated_event(resource_type, record)
+      when "DELETE"
+        publish_deleted_event(resource_type, id)
+      end
+    end
+
+    def publish_created_event(resource_type, record)
+      if resource_type == "Users"
+        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: resource_type,
+          correlation_id: @correlation_id
+        )
+      end
+    end
+
+    def publish_updated_event(resource_type, record)
+      if resource_type == "Users"
+        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: resource_type,
+          correlation_id: @correlation_id
+        )
+      end
+    end
+
+    def publish_deleted_event(resource_type, id)
+      if resource_type == "Users"
+        TwoPercent::Domain::Events::UserDeleted.create(
+          user_id: id,
+          correlation_id: @correlation_id
+        )
+      else
+        TwoPercent::Domain::Events::GroupDeleted.create(
+          group_id: id,
+          resource_type: resource_type,
+          correlation_id: @correlation_id
+        )
+      end
+    end
+
+    def find_record(resource_type, scim_id)
+      record =
+        if resource_type == "Users"
+          TwoPercent::ScimUser.find_by_scim_id(scim_id)
+        else
+          TwoPercent::ScimGroup.find_by_scim_id(scim_id)
+        end
+
+      raise ActiveRecord::RecordNotFound, "Resource \"#{scim_id}\" not found" unless record
+
+      record
+    end
   end
 end

data/lib/two_percent/configuration.rb

@@ -52,4 +52,19 @@ module TwoPercent
   # `TwoPercent.logger` will default to Rails.logger
   #
   config_accessor :logger
+
+  #
+  # HTTP header name for correlation ID tracking
+  # Defaults to "X-Correlation-Id" (common microservices pattern)
+  # Set to your IdP's correlation header (e.g., "SCIM-Request-ID")
+  #
+  # I.e.:
+  #
+  #   TwoPercent.configure do |config|
+  #     config.correlation_id_header = "SCIM-Request-ID"
+  #   end
+  #
+  config_accessor :correlation_id_header, default: "X-Correlation-Id"
+
+  class ConfigurationError < StandardError; end
 end

data/lib/two_percent/domain/events/base_event.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Domain
+    module Events
+      # Base class for domain events
+      # These are domain-focused, not SCIM-specific
+      class BaseEvent < AetherObservatory::EventBase
+        event_prefix "two_percent.domain"
+
+        attribute :correlation_id
+
+        # Apply this event to a domain model class
+        #
+        # Events know how to apply themselves to domain models, implementing
+        # the "tell, don't ask" principle and avoiding case statements.
+        #
+        # @param model_class [Class] The domain model class including Syncable
+        # @return [ActiveRecord::Base, nil] The affected record, if any
+        # @abstract Override in subclasses to implement event-specific logic
+        def apply_to_model(model_class)
+          raise NotImplementedError, "#{self.class} must implement #apply_to_model"
+        end
+      end
+    end
+  end
+end

data/lib/two_percent/domain/events/group_events.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Domain
+    module Events
+      # Domain event: Group was created
+      class GroupCreated < BaseEvent
+        event_name "group.created"
+
+        attribute :group_attributes  # Domain attributes, not SCIM
+        attribute :resource_type     # Groups, Departments, etc.
+
+        def group_id
+          group_attributes[:scim_id]
+        end
+
+        # Apply this event to a domain model class
+        def apply_to_model(model_class)
+          model_class.syncable_model.sync_created(group_attributes, model_class)
+        end
+      end
+
+      # Domain event: Group was updated
+      class GroupUpdated < BaseEvent
+        event_name "group.updated"
+
+        attribute :group_attributes
+        attribute :resource_type
+
+        def group_id
+          group_attributes[:scim_id]
+        end
+
+        # Apply this event to a domain model class
+        def apply_to_model(model_class)
+          model_class.syncable_model.sync_updated(group_attributes, model_class)
+        end
+      end
+
+      # Domain event: Group was deleted
+      class GroupDeleted < BaseEvent
+        event_name "group.deleted"
+
+        attribute :group_id # Just the ID for deletion
+        attribute :resource_type
+
+        # Apply this event to a domain model class
+        def apply_to_model(model_class)
+          model_class.syncable_model.sync_deleted(group_id, model_class)
+        end
+      end
+    end
+  end
+end