two_percent 0.5.0 → 1.0.0

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Domain
+    module Events
+      # Domain event: User was created
+      class UserCreated < BaseEvent
+        event_name "user.created"
+
+        attribute :user_attributes # Domain attributes, not SCIM
+
+        def user_id
+          user_attributes[:scim_id]
+        end
+
+        # Apply this event to a domain model class
+        def apply_to_model(model_class)
+          model_class.syncable_model.sync_created(user_attributes, model_class)
+        end
+      end
+
+      # Domain event: User was updated
+      class UserUpdated < BaseEvent
+        event_name "user.updated"
+
+        attribute :user_attributes
+
+        def user_id
+          user_attributes[:scim_id]
+        end
+
+        # Apply this event to a domain model class
+        def apply_to_model(model_class)
+          model_class.syncable_model.sync_updated(user_attributes, model_class)
+        end
+      end
+
+      # Domain event: User was deleted
+      class UserDeleted < BaseEvent
+        event_name "user.deleted"
+
+        attribute :user_id # Just the ID for deletion
+
+        # Apply this event to a domain model class
+        def apply_to_model(model_class)
+          model_class.syncable_model.sync_deleted(user_id, model_class)
+        end
+      end
+    end
+  end
+end

data/lib/two_percent/domain/events.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Domain
+    # Domain events (provider-agnostic)
+    module Events
+      autoload :BaseEvent, "two_percent/domain/events/base_event"
+      autoload :UserCreated, "two_percent/domain/events/user_events"
+      autoload :UserUpdated, "two_percent/domain/events/user_events"
+      autoload :UserDeleted, "two_percent/domain/events/user_events"
+      autoload :GroupCreated, "two_percent/domain/events/group_events"
+      autoload :GroupUpdated, "two_percent/domain/events/group_events"
+      autoload :GroupDeleted, "two_percent/domain/events/group_events"
+    end
+  end
+end

data/lib/two_percent/domain.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  # Domain layer - contains domain events and business logic
+  module Domain
+    autoload :Events, "two_percent/domain/events"
+  end
+end

data/lib/two_percent/scim/patch_processor.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Scim
+    # SCIM RFC 7644 PATCH operation processor
+    # Handles add, replace, remove operations on SCIM resources
+    class PatchProcessor
+      attr_reader :operations
+
+      def initialize(patch_request)
+        @operations = parse_operations(patch_request)
+      end
+
+      def apply_to_hash(scim_hash)
+        result = scim_hash.deep_dup
+
+        operations.each do |operation|
+          case operation[:op].downcase
+          when "add"
+            apply_add(result, operation[:path], operation[:value])
+          when "replace"
+            apply_replace(result, operation[:path], operation[:value])
+          when "remove"
+            apply_remove(result, operation[:path])
+          else
+            raise ArgumentError, "Unknown PATCH operation: #{operation[:op]}"
+          end
+        end
+
+        result
+      end
+
+    private
+
+      def parse_operations(patch_request)
+        ops = patch_request["Operations"] || patch_request[:Operations]
+        raise ArgumentError, "PATCH request must contain 'Operations' array" unless ops.is_a?(Array)
+
+        ops.flat_map do |op|
+          derive_operation(op)
+        end
+      end
+
+      def derive_operation(operation)
+        # Handle nested value hashes by flattening to path notation
+        case operation.fetch("value") { operation[:value] }
+        when Hash
+          operation.fetch("value") { operation[:value] }.flat_map do |key, value|
+            path = [operation.fetch("path") { operation[:path] }, key].compact.join(".")
+            derive_operation(
+              "op" => operation.fetch("op") { operation[:op] },
+              "path" => path,
+              "value" => value
+            )
+          end
+        else
+          [{
+            op: operation.fetch("op") { operation[:op] },
+            path: operation.fetch("path") { operation[:path] },
+            value: operation.fetch("value") { operation[:value] },
+          }]
+        end
+      end
+
+      def apply_add(hash, path, value)
+        if path.nil? || path.empty?
+          # No path means add to root
+          hash.merge!(value) if value.is_a?(Hash)
+        else
+          keys = path.split(".")
+          target = navigate_to_parent(hash, keys[0..-2])
+          last_key = keys.last
+
+          target[last_key] = if target[last_key].is_a?(Array)
+                               (target[last_key] + [value]).flatten
+                             else
+                               value
+                             end
+        end
+      end
+
+      def apply_replace(hash, path, value)
+        if path.nil? || path.empty?
+          # No path means replace root attributes
+          hash.merge!(value) if value.is_a?(Hash)
+        else
+          keys = path.split(".")
+          target = navigate_to_parent(hash, keys[0..-2])
+          target[keys.last] = value
+        end
+      end
+
+      def apply_remove(hash, path)
+        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
+        if last_key == "members"
+          target[last_key] = []
+        else
+          target.delete(last_key)
+        end
+      end
+
+      def navigate_to_parent(hash, keys)
+        return hash if keys.empty?
+
+        keys.reduce(hash) do |current, key|
+          current[key] ||= {}
+          current[key]
+        end
+      end
+    end
+  end
+end

data/lib/two_percent/scim/schema.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Scim
+    # SCIM Schema definition based on RFC 7644
+    class Schema
+      CORE_USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"
+      CORE_GROUP_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:Group"
+      EXTENSION_SCHEMA = "urn:ietf:params:scim:schemas:extension:authservice:2.0:User"
+
+      # Core User attributes per RFC 7644 Section 4.1
+      CORE_USER_ATTRIBUTES = %w[
+        id
+        externalId
+        userName
+        displayName
+        name
+        emails
+        phoneNumbers
+        addresses
+        photos
+        userType
+        title
+        active
+        groups
+        meta
+        schemas
+      ].freeze
+
+      # Core Group attributes per RFC 7644 Section 4.2
+      CORE_GROUP_ATTRIBUTES = %w[
+        id
+        externalId
+        displayName
+        members
+        meta
+        schemas
+      ].freeze
+
+      # Extension attributes (custom per IDP)
+      EXTENSION_USER_ATTRIBUTES = %w[
+        department
+        territory
+        territoryAbbr
+        role
+        mfaRequired
+      ].freeze
+
+      def self.validate_user(scim_hash, require_id: true)
+        # Accept either core schema or extension schemas
+        validate_schemas_present(scim_hash)
+
+        # Only require id for updates, not creation
+        required_attrs = require_id ? %w[id externalId] : %w[externalId]
+        validate_required_attributes(scim_hash, required_attrs)
+        validate_attribute_types(scim_hash)
+
+        # Return validated data with schemas normalized
+        normalize_user(scim_hash)
+      end
+
+      def self.validate_group(scim_hash, require_id: true)
+        # Accept either core schema or extension schemas
+        validate_schemas_present(scim_hash)
+
+        # Only require id for updates, not creation
+        required_attrs = require_id ? %w[id displayName] : %w[displayName]
+        validate_required_attributes(scim_hash, required_attrs)
+
+        normalize_group(scim_hash)
+      end
+
+      def self.normalize_user(scim_hash)
+        {
+          core: extract_core_attributes(scim_hash, CORE_USER_ATTRIBUTES),
+          extensions: extract_extensions(scim_hash),
+        }
+      end
+
+      def self.normalize_group(scim_hash)
+        {
+          core: extract_core_attributes(scim_hash, CORE_GROUP_ATTRIBUTES),
+          extensions: extract_extensions(scim_hash),
+        }
+      end
+
+      def self.extract_core_attributes(scim_hash, allowed_attrs)
+        scim_hash.slice(*allowed_attrs)
+      end
+
+      def self.extract_extensions(scim_hash)
+        scim_hash.select { |key, _| key.start_with?("urn:ietf:params:scim:schemas:extension:") }
+      end
+
+      def self.validate_schemas(scim_hash, required_schemas)
+        schemas = scim_hash["schemas"] || []
+        missing = required_schemas - schemas
+
+        return unless missing.any?
+
+        raise ArgumentError, "Missing required schemas: #{missing.join(', ')}"
+      end
+
+      def self.validate_schemas_present(scim_hash)
+        schemas = scim_hash["schemas"] || []
+
+        return unless schemas.empty?
+
+        raise ArgumentError, "schemas attribute is required"
+      end
+
+      def self.validate_required_attributes(scim_hash, required_attrs)
+        missing = required_attrs.select { |attr| scim_hash[attr].nil? }
+
+        return unless missing.any?
+
+        raise ArgumentError, "Missing required attributes: #{missing.join(', ')}"
+      end
+
+      def self.validate_attribute_types(scim_hash)
+        # Validate complex attribute structures
+        validate_name_structure(scim_hash["name"]) if scim_hash["name"]
+        validate_multi_valued(scim_hash["emails"], %w[value type]) if scim_hash["emails"]
+        validate_multi_valued(scim_hash["phoneNumbers"], %w[value type]) if scim_hash["phoneNumbers"]
+        validate_multi_valued(scim_hash["addresses"], %w[type]) if scim_hash["addresses"]
+        validate_multi_valued(scim_hash["photos"], %w[value type]) if scim_hash["photos"]
+      end
+
+      def self.validate_name_structure(name)
+        return unless name.is_a?(Hash)
+
+        valid_keys = %w[formatted familyName givenName middleName honorificPrefix honorificSuffix]
+        invalid = name.keys - valid_keys
+
+        return unless invalid.any?
+
+        raise ArgumentError, "Invalid name attributes: #{invalid.join(', ')}"
+      end
+
+      def self.validate_multi_valued(array, required_keys)
+        return unless array.is_a?(Array)
+
+        array.each_with_index do |item, idx|
+          raise ArgumentError, "Multi-valued attribute item #{idx} must be an object" unless item.is_a?(Hash)
+
+          missing = required_keys - item.keys
+          raise ArgumentError, "Multi-valued attribute item #{idx} missing: #{missing.join(', ')}" if missing.any?
+        end
+      end
+    end
+  end
+end

data/lib/two_percent/scim.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  module Scim
+    autoload :Schema, "two_percent/scim/schema"
+    autoload :PatchProcessor, "two_percent/scim/patch_processor"
+  end
+end

data/lib/two_percent/syncable.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module TwoPercent
+  # Syncable concern for syncing SCIM data to domain models
+  #
+  # This concern provides one-way synchronization from SCIM to your domain models,
+  # ensuring SCIM remains the source of truth for identity data.
+  #
+  # Usage:
+  #   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
+  #
+  #   class Group < ApplicationRecord
+  #     include TwoPercent::Syncable
+  #
+  #     syncable_as :group, scim_id_column: :scim_id do |scim_attrs|
+  #       { name: scim_attrs[:display_name], active: scim_attrs[:active] }
+  #     end
+  #   end
+  #
+  # This provides:
+  # - user.scim_user => linked ScimUser record
+  # - user.refresh_from_scim => pull latest data from SCIM
+  # - User.sync_from_scim_event(event) => sync from SCIM domain events
+  #
+  module Syncable
+    # Encapsulates type-specific SCIM synchronization logic
+    #
+    # This object replaces case statements and conditionals in the Syncable concern
+    # by encapsulating all knowledge about User vs Group differences.
+    #
+    class Model
+      attr_reader :scim_model_class, :scim_id_column, :resource_type, :options, :attribute_mapper_block
+
+      def initialize(scim_model_class:, scim_id_column:, resource_type:, **options, &block)
+        @scim_model_class = scim_model_class
+        @scim_id_column = scim_id_column
+        @resource_type = resource_type
+        @options = options
+        @attribute_mapper_block = block
+      end
+
+      # Setup association and validations on the domain model class
+      #
+      # @param domain_model_class [Class] The ActiveRecord model including Syncable
+      def setup_association(domain_model_class)
+        if scim_model_class == TwoPercent::ScimUser
+          setup_user_syncable(domain_model_class)
+        else
+          setup_group_syncable(domain_model_class)
+        end
+      end
+
+      # Setup ScimUser association and validations
+      #
+      # @param domain_model_class [Class] The ActiveRecord model including Syncable
+      def setup_user_syncable(domain_model_class)
+        domain_model_class.belongs_to :scim_user,
+                                      class_name: "TwoPercent::ScimUser",
+                                      foreign_key: scim_id_column,
+                                      primary_key: "scim_id",
+                                      optional: true
+
+        domain_model_class.validates scim_id_column, uniqueness: true, allow_nil: true
+      end
+
+      # Setup ScimGroup association and validations
+      #
+      # @param domain_model_class [Class] The ActiveRecord model including Syncable
+      def setup_group_syncable(domain_model_class)
+        domain_model_class.belongs_to :scim_group,
+                                      class_name: "TwoPercent::ScimGroup",
+                                      foreign_key: scim_id_column,
+                                      primary_key: "scim_id",
+                                      optional: true
+
+        domain_model_class.validates scim_id_column, uniqueness: true, allow_nil: true
+      end
+
+      # Sync created event to domain model
+      #
+      # @param attributes [Hash] SCIM attributes from event
+      # @param domain_model_class [Class] The domain model class
+      # @return [ActiveRecord::Base] The synced record
+      def sync_created(attributes, domain_model_class)
+        sync_upsert(attributes, domain_model_class)
+      end
+
+      # Sync updated event to domain model
+      #
+      # @param attributes [Hash] SCIM attributes from event
+      # @param domain_model_class [Class] The domain model class
+      # @return [ActiveRecord::Base] The synced record
+      def sync_updated(attributes, domain_model_class)
+        sync_upsert(attributes, domain_model_class)
+      end
+
+      # Sync deleted event to domain model
+      #
+      # @param scim_id [String] SCIM ID of deleted resource
+      # @param domain_model_class [Class] The domain model class
+      # @return [ActiveRecord::Base, nil] The destroyed record
+      def sync_deleted(scim_id, domain_model_class)
+        record = domain_model_class.find_by(scim_id_column => scim_id)
+        record&.destroy
+      end
+
+    private
+
+      # Shared logic for created/updated events
+      def sync_upsert(attributes, domain_model_class)
+        scim_id = attributes[:scim_id]
+        return unless scim_id
+
+        unless attribute_mapper_block
+          raise ArgumentError, "No attribute mapper block provided. Define one in syncable_as."
+        end
+
+        record = domain_model_class.find_or_initialize_by(scim_id_column => scim_id)
+        mapped_attrs = attribute_mapper_block.call(attributes)
+        record.assign_attributes(mapped_attrs)
+        record.save! if record.changed?
+        record
+      end
+    end
+
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :syncable_model
+    end
+
+    class_methods do
+      # Configure this model as syncable with SCIM
+      #
+      # @param type [Symbol] :user or :group
+      # @param scim_id_column [Symbol] Column storing SCIM ID (default: :scim_id)
+      # @param options [Hash] Additional configuration options
+      # @option options [String] :resource_type Resource type for groups (default: "Groups")
+      # @param block [Proc] Required block for custom attribute mapping from SCIM to domain
+      #
+      def syncable_as(type, scim_id_column: :scim_id, **options, &block)
+        scim_model_class = type == :user ? TwoPercent::ScimUser : TwoPercent::ScimGroup
+
+        self.syncable_model = Model.new(
+          scim_model_class: scim_model_class,
+          scim_id_column: scim_id_column,
+          resource_type: type,
+          **options,
+          &block
+        )
+
+        syncable_model.setup_association(self)
+      end
+
+      # Sync from a SCIM domain event
+      #
+      # Uses polymorphic dispatch - events know how to apply themselves
+      #
+      # @param event [TwoPercent::Domain::Events::Base] Domain event
+      # @return [ActiveRecord::Base, nil] The affected record, if any
+      #
+      def sync_from_scim_event(event)
+        event.apply_to_model(self)
+      end
+    end
+
+    # Instance methods
+
+    # Refresh this record from SCIM data
+    def refresh_from_scim
+      model = self.class.syncable_model
+      association_name = model.scim_model_class == TwoPercent::ScimUser ? :scim_user : :scim_group
+      scim_record = public_send(association_name)
+
+      return unless scim_record
+
+      unless model.attribute_mapper_block
+        raise ArgumentError, "No attribute mapper block provided. Define one in syncable_as."
+      end
+
+      attrs = scim_record.to_domain_attributes
+      mapped_attrs = model.attribute_mapper_block.call(attrs)
+      assign_attributes(mapped_attrs)
+      save! if changed?
+    end
+  end
+end

data/lib/two_percent/version.rb

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

data/lib/two_percent.rb

@@ -4,8 +4,10 @@ require "aether_observatory"
 
 require "two_percent/version"
 require "two_percent/configuration"
-require "two_percent/event_handler"
+require "two_percent/domain"
 require "two_percent/bulk_processor"
+require "two_percent/scim"
+require "two_percent/syncable"
 
 module TwoPercent
   # Logger used by TwoPercent. Defaults to Rails.logger

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: two_percent
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Carlos Palhares
 - Katie Edgar
 - Dan Smith
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aether_observatory
@@ -40,8 +39,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
-description: Adds a thin SCIM interface, and delegates the actions taken on write
-  calls to observers
+description: TwoPercent is a SCIM 2.0 Rails Engine with partial RFC 7644 protocol
+  compliance for IdP provisioning. Supports POST/PUT/PATCH/DELETE/Bulk operations
+  for Users and Groups, publishes domain events via AetherObservatory, and integrates
+  seamlessly with Rails applications.
 email:
 - carlos.palhares@powerhrg.com
 - katie.weber@powerhrg.com
@@ -55,18 +56,31 @@ files:
 - app/controllers/two_percent/application_controller.rb
 - app/controllers/two_percent/bulk_controller.rb
 - app/controllers/two_percent/scim_controller.rb
-- app/events/two_percent/application_event.rb
-- app/events/two_percent/create_event.rb
-- app/events/two_percent/delete_event.rb
-- app/events/two_percent/replace_event.rb
-- app/events/two_percent/update_event.rb
+- app/models/two_percent/application_record.rb
+- app/models/two_percent/scim_group.rb
+- app/models/two_percent/scim_group_membership.rb
+- app/models/two_percent/scim_user.rb
 - 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/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
+- lib/generators/two_percent/install/templates/two_percent.rb.erb
 - lib/tasks/two_percent_tasks.rake
 - lib/two_percent.rb
 - lib/two_percent/bulk_processor.rb
 - lib/two_percent/configuration.rb
+- lib/two_percent/domain.rb
+- lib/two_percent/domain/events.rb
+- lib/two_percent/domain/events/base_event.rb
+- lib/two_percent/domain/events/group_events.rb
+- lib/two_percent/domain/events/user_events.rb
 - lib/two_percent/engine.rb
-- lib/two_percent/event_handler.rb
+- lib/two_percent/scim.rb
+- lib/two_percent/scim/patch_processor.rb
+- lib/two_percent/scim/schema.rb
+- lib/two_percent/syncable.rb
 - lib/two_percent/version.rb
 homepage: https://github.com/powerhome/power-tools
 licenses:
@@ -76,7 +90,6 @@ metadata:
   source_code_uri: https://github.com/powerhome/power-tools
   changelog_uri: https://github.com/powerhome/power-tools/blob/main/packages/two_percent/docs/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -91,9 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Adds a thin SCIM interface, and delegates the actions taken on write calls
-  to observers
+summary: SCIM 2.0 Rails Engine for identity provisioning with domain event publishing
 test_files: []

data/app/events/two_percent/application_event.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module TwoPercent
-  class ApplicationEvent < AetherObservatory::EventBase
-    event_prefix "two_percent.scim"
-  end
-end

data/app/events/two_percent/create_event.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module TwoPercent
-  class CreateEvent < ApplicationEvent
-    event_name "create.all"
-    event_name { "create.#{resource}" }
-
-    attribute :resource
-    attribute :params
-  end
-end