command_tower 0.10.0 → 0.11.0

data/app/services/command_tower/services/application_service.rb

@@ -3,6 +3,8 @@
 module CommandTower
   module Services
     class ApplicationService < CommandTower::ServiceBase
+      include CommandTower::Transactional
+
       on_argument_validation :fail_early
 
       def self.inherited(subclass)
@@ -16,6 +18,41 @@ module CommandTower
           ServiceResult.from_interactor_context(interactor_context)
         end
       end
+
+      private
+
+      def acceptable_success_result?(result)
+        return true if result.nil?
+        return result.success? if result.is_a?(ServiceResult)
+
+        true
+      end
+
+      def acceptable_failure_result?(result)
+        return true if result.is_a?(ServiceResult) && result.failure?
+        return true if result.is_a?(CommandTower::Errors::ApplicationError)
+
+        false
+      end
+
+      def fail_transaction_type_error_message
+        "fail_transaction! requires a failed ServiceResult or ApplicationError"
+      end
+
+      def invalid_success_result_message(result)
+        "transaction block returned a non-success ServiceResult; " \
+          "use fail_transaction!(result) for expected failures (got #{result.class})"
+      end
+
+      def handle_transaction_failure(result)
+        context.fail!(application_error: application_error_from_transaction_result(result))
+      end
+
+      def application_error_from_transaction_result(result)
+        return result if result.is_a?(CommandTower::Errors::ApplicationError)
+
+        result.errors.first || CommandTower::Errors::InternalError.new
+      end
     end
   end
 end

data/app/services/command_tower/services/audit/events/filter_options.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Audit
+      module Events
+        # Projects safe filter-option metadata from the finalized audit registry.
+        # Not authorization — scoped catalogs only (Admin vs Me user_history).
+        class FilterOptions < CommandTower::Services::ApplicationService
+          ATTRIBUTION_MODE_LABELS = {
+            "self_service" => "Self-service",
+            "admin_direct" => "Admin action",
+            "impersonation" => "Impersonation",
+            "system" => "System"
+          }.freeze
+
+          validate :viewer_scope, is_a: Symbol, required: true
+
+          def call
+            unless %i[admin me].include?(viewer_scope)
+              raise CommandTower::Errors::ValidationError, "viewer_scope must be :admin or :me"
+            end
+
+            context.event_names = project_event_names
+            context.subject_types = project_subject_types
+            context.attribution_modes = project_attribution_modes
+          end
+
+          private
+
+          def scoped_definitions
+            definitions = CommandTower.config.registry.audit.definitions
+            if viewer_scope == :admin
+              definitions
+            else
+              definitions.select { |_name, definition| definition.user_history == true }
+            end
+          end
+
+          def project_event_names
+            scoped_definitions.sort_by { |name, _| name }.map do |name, definition|
+              label = definition.label.to_s.strip
+              label = name if label.empty?
+              {
+                value: name,
+                label:,
+                tags: Array(definition.tags)
+              }
+            end
+          end
+
+          def project_subject_types
+            scoped_definitions.filter_map do |_name, definition|
+              token = definition.subject_type.to_s.strip
+              next if token.empty?
+
+              { value: token, label: token }
+            end.uniq { |entry| entry[:value] }.sort_by { |entry| entry[:value] }
+          end
+
+          def project_attribution_modes
+            return [] unless viewer_scope == :admin
+
+            CommandTower::Audit::Event::ATTRIBUTION_MODES.map do |mode|
+              {
+                value: mode,
+                label: ATTRIBUTION_MODE_LABELS.fetch(mode, mode.tr("_", " ").split.map(&:capitalize).join(" "))
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/audit/events.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Audit
+      module Events
+        class List < CommandTower::Services::ApplicationService
+          VIEWER_SCOPES = %i[user admin].freeze
+
+          validate :viewer_scope, is_one: VIEWER_SCOPES, required: true
+          validate :limit, is_a: Integer, required: true, gte: 1, lte: 100
+          validate :offset, is_a: Integer, required: true, gt: -1
+          validate :affected_user_id, is_a: Integer, required: false
+          validate :actor_user_id, is_a: Integer, required: false
+          validate :originating_administrator_id, is_a: Integer, required: false
+          validate :actions, is_a: Array, required: false
+          validate :subject_types, is_a: Array, required: false
+          validate :attribution_mode, is_a: String, required: false
+          validate :occurred_after, is_a: [Time, ActiveSupport::TimeWithZone], required: false
+          validate :occurred_before, is_a: [Time, ActiveSupport::TimeWithZone], required: false
+          validate :principal, is_a: User, required: false
+          validate :scope_context, is_a: [CommandTower::AdminScope::ScopeContext, NilClass], required: false
+
+          def call
+            if user_scope? && affected_user_id.nil?
+              return context.fail!(application_error: CommandTower::Errors::InternalError.new)
+            end
+
+            relation = CommandTower::Audit::Event.order(occurred_at: :desc, id: :desc)
+            relation = apply_viewer_scope(relation)
+            relation = apply_admin_scope(relation)
+            relation = apply_present_filters(relation)
+
+            context.events = relation.limit(limit).offset(offset).to_a
+            context.pagination = { limit:, offset:, total_count: relation.count }
+          end
+
+          private
+
+          def user_scope?
+            viewer_scope == :user
+          end
+
+          def apply_viewer_scope(relation)
+            return relation.where(affected_user_id:, user_history: true) if user_scope?
+
+            relation
+          end
+
+          def apply_admin_scope(relation)
+            return relation unless admin_scope?
+
+            CommandTower::AdminScope::ApplyAuditScoping.call(
+              relation:,
+              scope_context:,
+              principal: principal || scope_context_principal
+            )
+          end
+
+          def admin_scope?
+            viewer_scope == :admin && scope_context.present?
+          end
+
+          def scope_context_principal
+            principal
+          end
+
+          def apply_present_filters(relation)
+            action_list = Array(actions).compact_blank
+            relation = relation.where(action: action_list) if action_list.any?
+            type_list = Array(subject_types).compact_blank
+            relation = relation.where(subject_type: type_list) if type_list.any?
+            relation = relation.where(occurred_at: occurred_after..) if occurred_after
+            relation = relation.where(occurred_at: ..occurred_before) if occurred_before
+            return relation if user_scope?
+
+            relation = relation.where(affected_user_id:) if affected_user_id
+            relation = relation.where(actor_user_id:) if actor_user_id
+            relation = relation.where(originating_administrator_id:) if originating_administrator_id
+            relation = relation.where(attribution_mode:) if attribution_mode.present?
+            relation
+          end
+        end
+
+        class Show < CommandTower::Services::ApplicationService
+          VIEWER_SCOPES = %i[user admin].freeze
+
+          validate :viewer_scope, is_one: VIEWER_SCOPES, required: true
+          validate :id, is_a: Integer, required: true
+          validate :affected_user_id, is_a: Integer, required: false
+          validate :principal, is_a: User, required: false
+          validate :scope_context, is_a: [CommandTower::AdminScope::ScopeContext, NilClass], required: false
+
+          def call
+            if viewer_scope == :user && affected_user_id.nil?
+              return context.fail!(application_error: CommandTower::Errors::InternalError.new)
+            end
+
+            relation = CommandTower::Audit::Event.where(id:)
+            if viewer_scope == :user
+              relation = relation.where(affected_user_id:, user_history: true)
+            elsif scope_context.present?
+              relation = CommandTower::AdminScope::ApplyAuditScoping.call(
+                relation:,
+                scope_context:,
+                principal: principal || scope_context_principal
+              )
+            end
+
+            event = relation.first
+            if event.nil?
+              return context.fail!(application_error: CommandTower::Errors::NotFoundError.new)
+            end
+
+            context.event = event
+          end
+
+          private
+
+          def scope_context_principal
+            principal
+          end
+        end
+
+        class Project < CommandTower::Services::ApplicationService
+          validate :event, is_a: CommandTower::Audit::Event, required: true
+          validate :viewer, is_one: %i[user admin], required: true
+
+          def call
+            changes = duplicate_hash(event.change_set)
+            mask_sensitive_changes!(changes)
+
+            context.projection = {
+              id: event.id,
+              event_name: event.action,
+              event_label: registry_label_for(event.action),
+              occurred_at: event.occurred_at,
+              attribution_mode: event.attribution_mode,
+              actor_user_id: event.actor_user_id,
+              affected_user_id: event.affected_user_id,
+              subject_type: event.subject_type,
+              subject_id: event.subject_id,
+              subject_label: event.subject_label,
+              impersonation_active: event.impersonation_active,
+              originating_administrator_id: event.originating_administrator_id,
+              changes:,
+              metadata: duplicate_hash(event.metadata)
+            }
+          end
+
+          private
+
+          def registry_label_for(action)
+            registry = CommandTower.config.registry.audit
+            return "" unless registry.registered?(action)
+
+            registry.fetch(action).label.to_s
+          end
+
+          def mask_sensitive_changes!(changes)
+            sensitivity_keys.each do |key|
+              entry = changes[key] || changes[key.to_sym]
+              next unless entry.is_a?(Hash)
+
+              changes.delete(key)
+              changes.delete(key.to_sym)
+              changes[key] = {
+                "from" => CommandTower::Audit::Masking.value(field: key, raw: hash_value(entry, "from")),
+                "to" => CommandTower::Audit::Masking.value(field: key, raw: hash_value(entry, "to"))
+              }
+            end
+          end
+
+          def sensitivity_keys
+            snapshot = Array(event.sensitive_fields).map(&:to_s)
+            snapshot | current_sensitive_fields
+          end
+
+          def current_sensitive_fields
+            registry = CommandTower.config.registry.audit
+            return [] unless registry.registered?(event.action)
+
+            Array(registry.fetch(event.action).sensitive_fields).map(&:to_s)
+          end
+
+          def duplicate_hash(value)
+            return {} unless value.is_a?(Hash)
+
+            value.deep_dup
+          end
+
+          def hash_value(entry, key)
+            entry[key] || entry[key.to_sym]
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/auth/assign_default_membership_role.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Auth
+      class AssignDefaultMembershipRole < CommandTower::Services::ApplicationService
+        validate :user, is_a: User, required: true
+
+        def call
+          role_name = CommandTower.config.authorization.default_membership_role
+          if role_name.nil?
+            context.user = user
+            return
+          end
+
+          unless role_present?(role_name)
+            context.fail!(
+              application_error: CommandTower::Errors::Auth::DefaultMembershipAssignmentError.new(
+                details: { role: role_name }
+              )
+            )
+          end
+
+          user.roles = (Array(user.roles) + [role_name.to_s]).uniq
+          unless user.save
+            context.fail!(
+              application_error: CommandTower::Errors::Auth::DefaultMembershipAssignmentError.new(
+                details: user.errors.to_hash
+              )
+            )
+          end
+
+          context.user = user
+        end
+
+        private
+
+        def role_present?(role_name)
+          role_name.to_s.strip.present? && CommandTower::Authorization::Role.roles[role_name].present?
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/auth/authenticate_session.rb

@@ -6,6 +6,7 @@ module CommandTower
       class AuthenticateSession < CommandTower::Services::ApplicationService
         validate :request_context, is_a: CommandTower::Auth::RequestContext, required: true
         validate :bypass_email_validation, is_one: [true, false], default: false
+        validate :overlay_mode, is_a: [Symbol, String, NilClass], required: false
 
         def call
           request = request_context.request
@@ -39,7 +40,23 @@ module CommandTower
             bypass_email_validation:
           )
           if auth_result.success?
-            context.user = auth_result.user
+            established = CommandTower::Impersonation::EstablishIdentity.call(
+              actor: auth_result.user,
+              impersonation_session_id: auth_result.impersonation_session_id,
+              mode: resolved_overlay_mode
+            )
+            if established.expired?
+              fail_authentication!(
+                CommandTower::Errors::Auth::ImpersonationSessionExpiredError.new,
+                token_source:,
+                impersonation_session_expired: true
+              )
+              return
+            end
+
+            context.user = established.user
+            context.actor_user = established.actor
+            context.impersonation_session_id = auth_result.impersonation_session_id
             context.token_expires_at = auth_result.expires_at
             context.generated_token = auth_result.generated_token if with_reset
             context.service_metadata = observation_metadata(
@@ -53,7 +70,8 @@ module CommandTower
           if auth_result.status == 412
             fail_authentication!(
               CommandTower::Errors::Auth::EmailVerificationRequiredError.new,
-              token_source:
+              token_source:,
+              email_verification_required: true
             )
             return
           end
@@ -63,24 +81,33 @@ module CommandTower
 
         private
 
-        def fail_authentication!(error, token_source:)
+        def fail_authentication!(error, token_source:, email_verification_required: false, impersonation_session_expired: false)
           context.service_metadata = observation_metadata(
             token_source:,
             authentication_failed: true,
-            cookie_authenticated: token_source == :cookie
+            cookie_authenticated: token_source == :cookie,
+            email_verification_required:,
+            impersonation_session_expired:
           )
           context.fail!(application_error: error)
         end
 
-        def observation_metadata(token_source:, authentication_failed:, cookie_authenticated: nil)
+        def observation_metadata(token_source:, authentication_failed:, cookie_authenticated: nil, email_verification_required: false, impersonation_session_expired: false)
           {
             token_source:,
             authentication_mechanism: :jwt,
             authentication_failed:,
-            cookie_authenticated: cookie_authenticated.nil? ? token_source == :cookie : cookie_authenticated
+            cookie_authenticated: cookie_authenticated.nil? ? token_source == :cookie : cookie_authenticated,
+            email_verification_required:,
+            impersonation_session_expired:
           }
         end
 
+        def resolved_overlay_mode
+          mode = overlay_mode.nil? ? :enforce : overlay_mode.to_sym
+          %i[enforce capture].include?(mode) ? mode : :enforce
+        end
+
         def csrf_error_for(message)
           case message
           when "csrf_mismatch"

data/app/services/command_tower/services/auth/email_verification/verify.rb

@@ -31,6 +31,8 @@ module CommandTower
 
             user.update(email_validated: true)
 
+            audit(:email_verified, subject: user, affected_user: user, changes: {})
+
             context.user = user.reload
             context.message = VERIFIED_MESSAGE
           end

data/app/services/command_tower/services/auth/password_reset/reset.rb

@@ -29,9 +29,19 @@ module CommandTower
             user.password = password
             user.password_confirmation = password_confirmation
 
-            unless user.save
-              log_error("Failed to update the password for user [#{user.id}]")
-              reject!(user.errors.to_hash.transform_values { Array(_1).join(", ") })
+            ActiveRecord::Base.transaction do
+              unless user.save
+                log_error("Failed to update the password for user [#{user.id}]")
+                reject!(user.errors.to_hash.transform_values { Array(_1).join(", ") })
+              end
+
+              audit(
+                :password_changed,
+                subject: user,
+                affected_user: user,
+                changes: {},
+                metadata: { mechanism: "reset" }
+              )
             end
 
             log_info("Password reset completed for user [#{user.id}]")

data/app/services/command_tower/services/auth/plain_text/login.rb

@@ -10,7 +10,10 @@ module CommandTower
 
           def call
             user = User.where(username: identifier).or(User.where(email: identifier)).first
-            invalid_credentials! if user.nil?
+            if user.nil?
+              audit_login_failed(affected_user: nil, outcome: "unknown_identifier")
+              invalid_credentials!
+            end
 
             if user.authenticate(password)
               user.successful_login += 1
@@ -20,6 +23,7 @@ module CommandTower
               user.password_consecutive_fail += 1
               user.save
               log_warn("Valid identifier. Incorrect password. Consecutive Password failures: #{user.password_consecutive_fail}")
+              audit_login_failed(affected_user: user, outcome: "invalid_password")
               invalid_credentials!
             end
 
@@ -34,6 +38,10 @@ module CommandTower
             context.fail!(application_error: CommandTower::Errors::Auth::InvalidCredentialsError.new)
           end
 
+          def audit_login_failed(affected_user:, outcome:)
+            audit(:login_failed, affected_user:, changes: {}, metadata: { outcome: })
+          end
+
           def token_expires_at_from_ttl
             CommandTower.config.jwt.ttl.from_now.to_time.to_s
           end

data/app/services/command_tower/services/auth/principal_capabilities/project.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Auth
+      module PrincipalCapabilities
+        # Projects possessed frontend-projectable capability ids for the effective user.
+        # Derives from composed RBAC grants ∩ curated principal_capabilities registry.
+        class Project < CommandTower::Services::ApplicationService
+          validate :user, is_a: User, required: true
+
+          def call
+            context.principal_capability_ids = possessed_capability_ids
+          end
+
+          private
+
+          def possessed_capability_ids
+            definitions = CommandTower.config.registry.principal_capabilities.definitions.values
+            ids =
+              if allow_everything?
+                definitions.map(&:id)
+              else
+                definitions.select { |definition| granted?(definition.required_entity) }.map(&:id)
+              end
+            ids.uniq.sort
+          end
+
+          def allow_everything?
+            Array(user.roles).any? do |role_name|
+              role = CommandTower::Authorization::Role.roles[role_name]
+              role&.allow_everything
+            end
+          end
+
+          def granted?(entity_name)
+            Array(user.roles).any? do |role_name|
+              role = CommandTower::Authorization::Role.roles[role_name]
+              next false unless role
+
+              role.allow_everything || role.entities.any? { |entity| entity.name.to_s == entity_name }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/impersonation/create.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Impersonation
+      class Create < CommandTower::Services::ApplicationService
+        validate :actor, is_a: User, required: true
+        validate :target, is_a: User, required: true
+
+        def call
+          now = Time.current
+          idle = CommandTower.config.impersonation.idle_timeout
+          absolute = CommandTower.config.impersonation.absolute_timeout
+
+          session = CommandTower::Impersonation::Session.create!(
+            actor_user_id: actor.id,
+            target_user_id: target.id,
+            started_at: now,
+            last_activity_at: now,
+            idle_expires_at: now + idle,
+            absolute_expires_at: now + absolute
+          )
+
+          context.session = session
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/impersonation/end.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Impersonation
+      class End < CommandTower::Services::ApplicationService
+        validate :session_id, is_a: String, required: true
+        validate :reason, is_a: String, required: true
+        validate :actor_user_id, is_a: Integer, required: false
+
+        def call
+          unless CommandTower::Impersonation::Session::END_REASONS.include?(reason)
+            return context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          end
+
+          now = Time.current
+          relation = CommandTower::Impersonation::Session.open.where(id: session_id)
+          relation = relation.where(actor_user_id:) if actor_user_id
+          updated = relation.update_all(ended_at: now, end_reason: reason, updated_at: now)
+
+          session = CommandTower::Impersonation::Session.find_by(id: session_id)
+          context.session = session
+          context.ended = updated.positive?
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/impersonation/record_activity.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Impersonation
+      class RecordActivity < CommandTower::Services::ApplicationService
+        validate :session_id, is_a: String, required: true
+
+        def call
+          now = Time.current
+          idle = CommandTower.config.impersonation.idle_timeout
+          CommandTower::Impersonation::Session.transaction do
+            session = CommandTower::Impersonation::Session.lock.find_by(id: session_id)
+            if session.nil? || !session.open? || session.expired?(at: now)
+              context.refreshed = false
+              return
+            end
+
+            session.update!(
+              last_activity_at: now,
+              idle_expires_at: now + idle
+            )
+            context.refreshed = true
+            context.session = session
+          end
+        end
+      end
+    end
+  end
+end