command_tower 0.10.0 → 0.11.0

data/app/workflows/command_tower/workflows/application_workflow.rb

@@ -3,25 +3,122 @@
 module CommandTower
   module Workflows
     class ApplicationWorkflow
+      include CommandTower::Transactional
+      include CommandTower::Execution::ContextAccess
+      include CommandTower::Logging::LifecycleDeclaration
+      include CommandTower::Impersonation::ActivityDeclaration
+      log_lifecycle!
+
+      TransactionFailure = CommandTower::Transactional::TransactionFailure
+      InvalidTransactionResult = CommandTower::Transactional::InvalidTransactionResult
+
+      ALLOWED_RETRY_STRATEGIES = %i[none delayed_continuation scheduled_cadence].freeze
+
+      protected :transaction, :fail_transaction!
+
+      # Programmer error: deferred result used with a strategy that forbids continuation.
+      class InvalidDeferredResult < StandardError; end
+
+      # Programmer error: delayed continuation requires a job instance to replay.
+      class DelayedContinuationRequiresJob < StandardError; end
+
       class << self
         def call(**args)
           validate_retry_strategy!
-          begin
-            new.call(**args)
-          rescue StandardError => e
-            log_unknown_exception(e)
-            WorkflowResult.failure(
-              errors: [CommandTower::Errors::InternalError.new(cause: e)],
-              http_status: :internal_server_error
-            )
+          CommandTower::Events.around_execution(layer: :workflow, subject: name, log_lifecycle: lifecycle_loggable?) do |record|
+            begin
+              record[:result] = new.call(**args)
+            rescue TransactionFailure => e
+              record[:result] = e.result
+            rescue InvalidTransactionResult
+              raise
+            rescue StandardError => e
+              record[:unexpected] = e
+              record[:result] = WorkflowResult.failure(
+                errors: [CommandTower::Errors::InternalError.new(cause: e)],
+                http_status: :internal_server_error
+              )
+            end
+            mark_impersonation_activity!(record[:result])
+          end
+        end
+
+        # Job transport entry. Unexpected exceptions re-raise. Deferred continuation
+        # is scheduled by CommandTower when the strategy is :delayed_continuation.
+        def call_from_job(job: nil, continuation_attempt: 1, **args)
+          validate_retry_strategy!
+          result = invoke_for_job(**args)
+          handle_job_result(
+            result,
+            job: job,
+            continuation_attempt: Integer(continuation_attempt),
+            **args
+          )
+        end
+
+        def retry_strategy(strategy, max_attempts: nil)
+          @retry_strategy = strategy&.to_sym
+          @continuation_max_attempts = max_attempts
+        end
+
+        def declared_retry_strategy
+          @retry_strategy
+        end
+
+        def continuation_max_attempts
+          @continuation_max_attempts
+        end
+
+        def mark_impersonation_activity!(result)
+          return unless impersonation_activity?
+          return unless result.is_a?(CommandTower::Workflows::WorkflowResult) && result.success?
+
+          CommandTower::Current.impersonation_activity_recorded = true
+        end
+        private :mark_impersonation_activity!
+
+        def validate_retry_strategy!
+          raise "#{name} must declare retry_strategy (:none, :delayed_continuation, or :scheduled_cadence)" if @retry_strategy.nil?
+
+          if @retry_strategy == :sidekiq
+            raise "#{name} retry_strategy :sidekiq is not supported; use :delayed_continuation"
+          end
+
+          unless ALLOWED_RETRY_STRATEGIES.include?(@retry_strategy)
+            raise "#{name} retry_strategy #{@retry_strategy.inspect} is invalid " \
+                  "(allowed: :none, :delayed_continuation, :scheduled_cadence)"
+          end
+
+          if @retry_strategy == :delayed_continuation
+            max = @continuation_max_attempts
+            unless max.is_a?(Integer) && max >= 1
+              raise "#{name} retry_strategy :delayed_continuation requires max_attempts: >= 1"
+            end
+          elsif !@continuation_max_attempts.nil?
+            raise "#{name} retry_strategy #{@retry_strategy.inspect} cannot declare max_attempts"
           end
         end
 
-        # Job transport entry: same WorkflowResult as `.call`, but raises when the
-        # workflow marks the failure for ActiveJob propagation (`meta[:propagate_to_job]`).
-        # Controllers continue to use `.call` and render envelopes from WorkflowResult.
-        def call_from_job(**args)
-          result = call(**args)
+        private
+
+        def invoke_for_job(**args)
+          CommandTower::Events.around_execution(layer: :workflow, subject: name, log_lifecycle: lifecycle_loggable?) do |record|
+            begin
+              record[:result] = new.call(**args)
+            rescue TransactionFailure => e
+              record[:result] = e.result
+            rescue StandardError => e
+              record[:unexpected] = e
+              raise
+            end
+          end
+        end
+
+        def handle_job_result(result, job:, continuation_attempt:, **args)
+          if result.deferred?
+            return handle_deferred(result, job: job, continuation_attempt: continuation_attempt, **args)
+          end
+
           if result.failure? && result.meta[:propagate_to_job]
             error = Array(result.errors).first
             raise error if error
@@ -32,21 +129,29 @@ module CommandTower
           result
         end
 
-        def retry_strategy(strategy)
-          @retry_strategy = strategy
-        end
+        def handle_deferred(result, job:, continuation_attempt:, **args)
+          unless @retry_strategy == :delayed_continuation
+            raise InvalidDeferredResult,
+                  "#{name} returned deferred but retry_strategy is #{@retry_strategy.inspect}"
+          end
 
-        def validate_retry_strategy!
-          return if @retry_strategy
+          max_attempts = Integer(@continuation_max_attempts)
+          if continuation_attempt >= max_attempts
+            raise CommandTower::Errors::ContinuationExhaustedError.new(
+              details: { attempt: continuation_attempt, max_attempts: max_attempts }
+            )
+          end
 
-          raise "#{name} must declare retry_strategy (:none, :sidekiq, or :scheduled_cadence)"
-        end
+          if job.nil?
+            raise DelayedContinuationRequiresJob,
+                  "#{name} deferred continuation requires call_from_job(job:)"
+          end
 
-        def log_unknown_exception(exception)
-          Rails.logger.error(
-            "[#{name}] Unknown workflow exception: #{exception.class}: #{exception.message}\n" \
-            "#{exception.backtrace&.join("\n")}"
+          wait = [Integer(result.retry_after), 1].max
+          job.class.set(wait: wait.seconds).perform_later(
+            **args.merge(continuation_attempt: continuation_attempt + 1)
           )
+          result
         end
       end
 
@@ -63,6 +168,40 @@ module CommandTower
       def failure(errors:, http_status:, response_effects: nil, meta: {})
         WorkflowResult.failure(errors:, http_status:, response_effects:, meta:)
       end
+
+      def deferred(reason:, retry_after:, payload: {}, http_status: :accepted, response_effects: nil, meta: {})
+        WorkflowResult.deferred(
+          reason:,
+          retry_after:,
+          payload:,
+          http_status:,
+          response_effects:,
+          meta:
+        )
+      end
+
+      private
+
+      def acceptable_success_result?(result)
+        result.is_a?(WorkflowResult) && result.success?
+      end
+
+      def acceptable_failure_result?(result)
+        result.is_a?(WorkflowResult) && result.failure?
+      end
+
+      def fail_transaction_type_error_message
+        "fail_transaction! requires a failed WorkflowResult"
+      end
+
+      def invalid_success_result_message(result)
+        unless result.is_a?(WorkflowResult)
+          return "transaction block must return a WorkflowResult; got #{result.class}"
+        end
+
+        "transaction block returned a non-success WorkflowResult; " \
+          "use fail_transaction!(failure(...)) for expected failures"
+      end
     end
   end
 end

data/app/workflows/command_tower/workflows/audit/error_mapping.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module ErrorMapping
+        module_function
+
+        def http_status_for(error)
+          case error
+          when CommandTower::Errors::ValidationError
+            :unprocessable_entity
+          when CommandTower::Errors::ForbiddenError
+            :forbidden
+          when CommandTower::Errors::NotFoundError
+            :not_found
+          else
+            :internal_server_error
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/audit/events/filter_options_for_admin_workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module Events
+        class FilterOptionsForAdminWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call
+            projected = CommandTower::Services::Audit::Events::FilterOptions.call(viewer_scope: :admin)
+            return result_or_failure(projected) unless projected.success?
+
+            payload = CommandTower::Serializers::Audit::Events::FilterOptionsSerializer.serialize(
+              event_names: projected.data[:event_names],
+              subject_types: projected.data[:subject_types],
+              attribution_modes: projected.data[:attribution_modes]
+            )
+            success(payload:, http_status: :ok)
+          end
+
+          private
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Audit::ErrorMapping.http_status_for(result.errors.first)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/audit/events/filter_options_for_user_workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module Events
+        class FilterOptionsForUserWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call
+            projected = CommandTower::Services::Audit::Events::FilterOptions.call(viewer_scope: :me)
+            return result_or_failure(projected) unless projected.success?
+
+            payload = CommandTower::Serializers::Audit::Events::FilterOptionsSerializer.serialize(
+              event_names: projected.data[:event_names],
+              subject_types: projected.data[:subject_types],
+              attribution_modes: projected.data[:attribution_modes]
+            )
+            success(payload:, http_status: :ok)
+          end
+
+          private
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Audit::ErrorMapping.http_status_for(result.errors.first)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/audit/events/list_for_admin_workflow.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module Events
+        class ListForAdminWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(
+            limit:,
+            offset:,
+            user:,
+            scope_value: nil,
+            actions: nil,
+            occurred_after: nil,
+            occurred_before: nil,
+            subject_types: nil,
+            affected_user_id: nil,
+            actor_user_id: nil,
+            originating_administrator_id: nil,
+            attribution_mode: nil
+          )
+            scope_result = resolve_scope(user:, scope_value:)
+            return scope_result if scope_result.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            listed = CommandTower::Services::Audit::Events::List.call(
+              viewer_scope: :admin,
+              limit:,
+              offset:,
+              actions:,
+              occurred_after:,
+              occurred_before:,
+              subject_types:,
+              affected_user_id:,
+              actor_user_id:,
+              originating_administrator_id:,
+              attribution_mode:,
+              principal: user,
+              scope_context: scope_result
+            )
+            return result_or_failure(listed) unless listed.success?
+
+            payload = listed.data[:events].filter_map do |event|
+              projected = CommandTower::Services::Audit::Events::Project.call(event:, viewer: :admin)
+              return result_or_failure(projected) unless projected.success?
+
+              CommandTower::Serializers::Audit::Events::EventSerializer.serialize(projected.data[:projection])
+            end
+            meta = CommandTower::Serializers::Audit::Events::PaginationMetaSerializer.serialize(listed.data[:pagination])
+            success(payload:, meta:, http_status: :ok)
+          end
+
+          private
+
+          def resolve_scope(user:, scope_value:)
+            CommandTower::Workflows::Admin::ScopeResolution.resolve(
+              tool_id: "audit",
+              user:,
+              scope_value:
+            )
+          end
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Audit::ErrorMapping.http_status_for(result.errors.first)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/audit/events/list_for_user_workflow.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module Events
+        class ListForUserWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(user:, limit:, offset:, actions: nil, occurred_after: nil, occurred_before: nil, subject_types: nil)
+            listed = CommandTower::Services::Audit::Events::List.call(
+              viewer_scope: :user,
+              affected_user_id: user.id,
+              limit:,
+              offset:,
+              actions:,
+              occurred_after:,
+              occurred_before:,
+              subject_types:
+            )
+            return result_or_failure(listed) unless listed.success?
+
+            payload = listed.data[:events].filter_map do |event|
+              projected = CommandTower::Services::Audit::Events::Project.call(event:, viewer: :user)
+              return result_or_failure(projected) unless projected.success?
+
+              CommandTower::Serializers::Audit::Events::EventSerializer.serialize(projected.data[:projection])
+            end
+            meta = CommandTower::Serializers::Audit::Events::PaginationMetaSerializer.serialize(listed.data[:pagination])
+            success(payload:, meta:, http_status: :ok)
+          end
+
+          private
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Audit::ErrorMapping.http_status_for(result.errors.first)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/audit/events/show_for_admin_workflow.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module Events
+        class ShowForAdminWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(id:, user:, scope_value: nil)
+            scope_result = resolve_scope(user:, scope_value:)
+            return scope_result if scope_result.is_a?(CommandTower::Workflows::WorkflowResult)
+
+            shown = CommandTower::Services::Audit::Events::Show.call(
+              viewer_scope: :admin,
+              id:,
+              principal: user,
+              scope_context: scope_result
+            )
+            return result_or_failure(shown) unless shown.success?
+
+            projected = CommandTower::Services::Audit::Events::Project.call(
+              event: shown.data[:event],
+              viewer: :admin
+            )
+            return result_or_failure(projected) unless projected.success?
+
+            payload = CommandTower::Serializers::Audit::Events::EventSerializer.serialize(
+              projected.data[:projection]
+            )
+            success(payload:, http_status: :ok)
+          end
+
+          private
+
+          def resolve_scope(user:, scope_value:)
+            CommandTower::Workflows::Admin::ScopeResolution.resolve(
+              tool_id: "audit",
+              user:,
+              scope_value:
+            )
+          end
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Audit::ErrorMapping.http_status_for(result.errors.first)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/audit/events/show_for_user_workflow.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Audit
+      module Events
+        class ShowForUserWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(user:, id:)
+            shown = CommandTower::Services::Audit::Events::Show.call(
+              viewer_scope: :user,
+              affected_user_id: user.id,
+              id:
+            )
+            return result_or_failure(shown) unless shown.success?
+
+            projected = CommandTower::Services::Audit::Events::Project.call(
+              event: shown.data[:event],
+              viewer: :user
+            )
+            return result_or_failure(projected) unless projected.success?
+
+            payload = CommandTower::Serializers::Audit::Events::EventSerializer.serialize(
+              projected.data[:projection]
+            )
+            success(payload:, http_status: :ok)
+          end
+
+          private
+
+          def result_or_failure(result)
+            failure(
+              errors: result.errors,
+              http_status: CommandTower::Workflows::Audit::ErrorMapping.http_status_for(result.errors.first)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/auth/authenticate_request_workflow.rb

@@ -6,11 +6,12 @@ module CommandTower
       class AuthenticateRequestWorkflow < CommandTower::Workflows::ApplicationWorkflow
         retry_strategy :none
 
-        def call(request:, response:, bypass_email_validation: false)
+        def call(request:, response:, bypass_email_validation: false, overlay_mode: :enforce)
           request_context = CommandTower::Auth::RequestContext.from(request, response)
           auth_result = CommandTower::Services::Auth::AuthenticateSession.call(
             request_context: request_context,
-            bypass_email_validation: bypass_email_validation
+            bypass_email_validation: bypass_email_validation,
+            overlay_mode: overlay_mode
           )
 
           unless auth_result.success?

data/app/workflows/command_tower/workflows/auth/authentication_response_effects.rb

@@ -10,7 +10,11 @@ module CommandTower
 
         def for_auth_failure(metadata)
           effects = {}
-          if metadata[:cookie_authenticated] && metadata[:authentication_failed]
+          # 412 email verification is a live session that still needs the JWT
+          # cookie so the client can send/verify the code.
+          if metadata[:cookie_authenticated] && metadata[:authentication_failed] &&
+              !metadata[:email_verification_required] &&
+              !metadata[:impersonation_session_expired]
             effects[:clear_auth_cookie] = true
           end
           effects

data/app/workflows/command_tower/workflows/auth/logout_workflow.rb

@@ -6,13 +6,53 @@ module CommandTower
       class LogoutWorkflow < CommandTower::Workflows::ApplicationWorkflow
         retry_strategy :none
 
-        def call(input: nil, request_context: nil)
+        def call(token: nil)
+          maybe_audit_session_cleared(token)
           success(
             payload: CommandTower::Serializers::Auth::LogoutResponseSerializer.serialize,
             http_status: :ok,
             response_effects: { clear_token: true }
           )
         end
+
+        private
+
+        def maybe_audit_session_cleared(token)
+          return if token.to_s.strip.empty?
+
+          outcome = CommandTower::Jwt::AuthenticateUser.(token:, bypass_email_validation: true)
+          return unless outcome.success?
+
+          end_overlay_session(outcome)
+          audit(:session_cleared, affected_user: outcome.user, changes: {})
+        end
+
+        def end_overlay_session(outcome)
+          session_id = outcome.impersonation_session_id.to_s.strip
+          return if session_id.empty?
+
+          ended = CommandTower::Services::Impersonation::End.call(
+            session_id:,
+            reason: "logout",
+            actor_user_id: outcome.user.id
+          )
+          return unless ended.success? && ended.data[:ended]
+
+          session = ended.data[:session]
+          target = User.find_by(id: session.target_user_id)
+          return if target.nil?
+
+          CommandTower::Impersonation::ClearOverlayForAudit.call(actor_user_id: outcome.user.id) do
+            audit(
+              :impersonation_ended,
+              subject: target,
+              affected_user: target,
+              changes: { reason: { from: nil, to: "logout" } },
+              metadata: { impersonation_session_id: session.id },
+              attribution_mode: :admin_direct
+            )
+          end
+        end
       end
     end
   end

data/app/workflows/command_tower/workflows/auth/plain_text/login_workflow.rb

@@ -15,6 +15,8 @@ module CommandTower
 
             if login_result.success?
               data = login_result.data
+              CommandTower::Execution::IdentityEnrichment.from_user(data[:user])
+              audit(:session_created, affected_user: data[:user], changes: {})
               return success(
                 payload: CommandTower::Serializers::Auth::LoginResponseSerializer.serialize(
                   user: data[:user],

data/app/workflows/command_tower/workflows/auth/principal_capabilities/show_workflow.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Auth
+      module PrincipalCapabilities
+        class ShowWorkflow < CommandTower::Workflows::ApplicationWorkflow
+          retry_strategy :none
+
+          def call(user:)
+            result = CommandTower::Services::Auth::PrincipalCapabilities::Project.call(user:)
+            unless result.success?
+              return failure(errors: result.errors, http_status: :unprocessable_entity)
+            end
+
+            success(
+              payload: CommandTower::Serializers::Auth::PrincipalCapabilitiesSerializer.serialize(
+                result.data[:principal_capability_ids]
+              ),
+              http_status: :ok
+            )
+          end
+        end
+      end
+    end
+  end
+end