command_tower 0.10.0 → 0.11.0

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

@@ -15,31 +15,64 @@ module CommandTower
             )
           end
 
-          register_result = CommandTower::Services::Auth::Register.call(
-            first_name: input.first_name,
-            last_name: input.last_name,
-            username: input.username,
-            email: input.email,
-            password: input.password,
-            password_confirmation: input.password_confirmation
-          )
+          user = nil
+          result = transaction do
+            register_result = CommandTower::Services::Auth::Register.call(
+              first_name: input.first_name,
+              last_name: input.last_name,
+              username: input.username,
+              email: input.email,
+              password: input.password,
+              password_confirmation: input.password_confirmation
+            )
+            unless register_result.success?
+              fail_transaction!(
+                failure(
+                  errors: register_result.errors,
+                  http_status: SignupErrorStatus.http_status_for(register_result.errors.first)
+                )
+              )
+            end
 
-          unless register_result.success?
-            return failure(
-              errors: register_result.errors,
-              http_status: SignupErrorStatus.http_status_for(register_result.errors.first)
+            user = register_result.data[:user]
+            audit(
+              :user_registered,
+              subject: user,
+              affected_user: user,
+              changes: {}
             )
-          end
 
-          user = register_result.data[:user]
-          emit_welcome(user)
+            roles_before = Array(user.roles)
+            assign_result = CommandTower::Services::Auth::AssignDefaultMembershipRole.call(user: user)
+            unless assign_result.success?
+              fail_transaction!(
+                failure(
+                  errors: assign_result.errors,
+                  http_status: :unprocessable_entity
+                )
+              )
+            end
 
-          success(
-            payload: CommandTower::Serializers::Auth::RegisterResponseSerializer.serialize(
-              user: user
-            ),
-            http_status: :created
-          )
+            user = assign_result.data[:user]
+            assigned_roles = Array(user.roles) - roles_before
+            if assigned_roles.any?
+              audit(
+                :role_assigned,
+                subject: user,
+                affected_user: user,
+                changes: { role: { from: nil, to: assigned_roles.first.to_s } }
+              )
+            end
+            success(
+              payload: CommandTower::Serializers::Auth::RegisterResponseSerializer.serialize(
+                user: user
+              ),
+              http_status: :created
+            )
+          end
+
+          emit_welcome(user) if result.success? && user.present?
+          result
         end
 
         private
@@ -69,13 +102,12 @@ module CommandTower
 
         def log_welcome_failure(user, error)
           payload = {
-            event: "messaging.welcome_produce_failed",
             user_id: user.id,
             error_class: error.class.name,
+            log_level: :error
           }
           payload[:error_code] = error.code if error.respond_to?(:code)
-          payload[:error_message] = error.message if error.respond_to?(:message)
-          Rails.logger.error(payload.to_json)
+          publish_event(category: :messaging, name: :welcome_produce_failed, payload:)
         end
       end
     end

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

@@ -20,10 +20,14 @@ module CommandTower
               response_effects[:ensure_csrf_cookie] = { rotate: csrf_rotate_on_reset? }
             end
 
+            impersonation_session = impersonation_session_for(auth_context)
+
             success(
               payload: CommandTower::Serializers::Auth::SessionResponseSerializer.serialize(
                 user: current_user,
-                token_expires_at: auth_context.token_expires_at
+                token_expires_at: auth_context.token_expires_at,
+                impersonation_session:,
+                actor: auth_context.actor_user
               ),
               http_status: :ok,
               response_effects: response_effects
@@ -37,6 +41,16 @@ module CommandTower
 
             CommandTower.config.jwt.cookie.csrf.rotate_on_reset
           end
+
+          def impersonation_session_for(auth_context)
+            return unless CommandTower::Current.impersonation_active
+
+            session_id = auth_context.impersonation_session_id.presence ||
+              CommandTower::Current.impersonation_session_id
+            return if session_id.blank?
+
+            CommandTower::Impersonation::Session.find_by(id: session_id)
+          end
         end
       end
     end

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

@@ -18,6 +18,7 @@ module CommandTower
                CommandTower::Errors::ForbiddenError
             :forbidden
           when CommandTower::Errors::Auth::InvalidCredentialsError,
+               CommandTower::Errors::Auth::ImpersonationSessionExpiredError,
                CommandTower::Errors::UnauthorizedError
             :unauthorized
           else

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Impersonation
+      module ErrorMapping
+        module_function
+
+        def http_status_for(error)
+          case error
+          when CommandTower::Errors::Auth::SelfImpersonationError,
+               CommandTower::Errors::Auth::ImpersonationSessionMissingError,
+               CommandTower::Errors::ValidationError
+            :unprocessable_entity
+          when CommandTower::Errors::Auth::NestedImpersonationError,
+               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/impersonation/start_workflow.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Impersonation
+      class StartWorkflow < CommandTower::Workflows::ApplicationWorkflow
+        retry_strategy :none
+
+        def call(id:, actor:, scope_value: nil)
+          if CommandTower::Current.impersonation_active
+            return failure(
+              errors: [CommandTower::Errors::Auth::NestedImpersonationError.new],
+              http_status: :forbidden
+            )
+          end
+
+          if actor.id == id
+            return failure(
+              errors: [CommandTower::Errors::Auth::SelfImpersonationError.new],
+              http_status: :unprocessable_entity
+            )
+          end
+
+          scope_result = CommandTower::Workflows::Admin::ScopeResolution.resolve(
+            tool_id: "users",
+            user: actor,
+            scope_value:
+          )
+          return scope_result if scope_result.is_a?(CommandTower::Workflows::WorkflowResult)
+
+          shown = CommandTower::Services::Admin::Users::Show.call(
+            id:,
+            principal: actor,
+            scope_context: scope_result
+          )
+          unless shown.success?
+            return failure(
+              errors: shown.errors,
+              http_status: CommandTower::Workflows::Admin::Users::ErrorMapping.http_status_for(shown.errors.first)
+            )
+          end
+
+          target = shown.data[:user]
+          created = CommandTower::Services::Impersonation::Create.call(actor:, target:)
+          unless created.success?
+            return failure(
+              errors: created.errors,
+              http_status: :internal_server_error
+            )
+          end
+
+          session = created.data[:session]
+          audit_started(session:, target:, scope_context: scope_result)
+
+          token = CommandTower::Jwt::LoginCreate.call(
+            user: actor,
+            impersonation_session_id: session.id
+          ).token
+          expires_at = CommandTower.config.jwt.ttl.from_now.to_time.to_s
+
+          success(
+            payload: CommandTower::Serializers::Impersonation::SessionSerializer.serialize(session),
+            http_status: :created,
+            response_effects: {
+              set_token: { token:, expires_at: }
+            }
+          )
+        end
+
+        private
+
+        def audit_started(session:, target:, scope_context:)
+          scope_class, host_context = audit_scope_for(scope_context)
+          audit(
+            :impersonation_started,
+            subject: target,
+            affected_user: target,
+            metadata: { impersonation_session_id: session.id },
+            attribution_mode: :admin_direct,
+            scope_class:,
+            host_context:
+          )
+        end
+
+        def audit_scope_for(scope_context)
+          return [:global, nil] if scope_context.nil?
+          return [:global, nil] unless CommandTower.config.admin_scope.registered?("users")
+
+          type = CommandTower.config.admin_scope.fetch("users").host_context_type
+          return [:global, nil] if type.to_s.strip.empty?
+
+          [:host, { type:, identifier: scope_context.scope_value }]
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/impersonation/stop_workflow.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Impersonation
+      class StopWorkflow < CommandTower::Workflows::ApplicationWorkflow
+        retry_strategy :none
+
+        def call(actor:, impersonation_session_id:, token_expires_at: nil)
+          session_id = impersonation_session_id.to_s.strip
+          if session_id.empty?
+            return failure(
+              errors: [CommandTower::Errors::Auth::ImpersonationSessionMissingError.new],
+              http_status: :unprocessable_entity
+            )
+          end
+
+          ended = CommandTower::Services::Impersonation::End.call(
+            session_id:,
+            reason: "manual",
+            actor_user_id: actor.id
+          )
+          unless ended.success?
+            return failure(
+              errors: ended.errors,
+              http_status: CommandTower::Workflows::Impersonation::ErrorMapping.http_status_for(ended.errors.first)
+            )
+          end
+
+          session = ended.data[:session]
+          if session.nil? || session.actor_user_id != actor.id
+            return failure(
+              errors: [CommandTower::Errors::Auth::ImpersonationSessionMissingError.new],
+              http_status: :unprocessable_entity
+            )
+          end
+
+          if ended.data[:ended]
+            target = User.find_by(id: session.target_user_id)
+            if target
+              audit(
+                :impersonation_ended,
+                subject: target,
+                affected_user: target,
+                changes: { reason: { from: nil, to: "manual" } },
+                metadata: { impersonation_session_id: session.id },
+                attribution_mode: CommandTower::Current.impersonation_active ? nil : :admin_direct
+              )
+            end
+          end
+
+          token = CommandTower::Jwt::LoginCreate.call(user: actor).token
+          expires_at = token_expires_at.presence || CommandTower.config.jwt.ttl.from_now.to_time.to_s
+
+          success(
+            payload: { message: "impersonation_ended" },
+            http_status: :ok,
+            response_effects: {
+              set_token: { token:, expires_at: }
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/update_name_workflow.rb

@@ -5,6 +5,7 @@ module CommandTower
     module Me
       class UpdateNameWorkflow < CommandTower::Workflows::ApplicationWorkflow
         retry_strategy :none
+        impersonation_activity!
 
         def call(current_user:, first_name:, last_name:, auth_context: nil)
           update_result = CommandTower::Services::Me::UpdateName.call(

data/app/workflows/command_tower/workflows/profile/show_workflow.rb

@@ -5,6 +5,7 @@ module CommandTower
     module Profile
       class ShowWorkflow < CommandTower::Workflows::ApplicationWorkflow
         retry_strategy :none
+        impersonation_activity!
 
         def call(current_user:, auth_context: nil)
           success(

data/app/workflows/command_tower/workflows/workflow_result.rb

@@ -3,31 +3,55 @@
 module CommandTower
   module Workflows
     class WorkflowResult
-      attr_reader :payload, :errors, :http_status, :response_effects, :meta
+      STATUSES = %i[success deferred failure].freeze
+
+      attr_reader :payload, :errors, :http_status, :response_effects, :meta, :reason, :retry_after
+
+      def initialize(status:, payload:, errors:, http_status:, response_effects: nil, meta: {},
+                     reason: nil, retry_after: nil)
+        @status = status.to_sym
+        raise ArgumentError, "invalid WorkflowResult status #{@status}" unless STATUSES.include?(@status)
 
-      def initialize(success:, payload:, errors:, http_status:, response_effects: nil, meta: {})
-        @success = success
         @payload = payload
         @errors = errors
         @http_status = http_status
         @response_effects = response_effects
         @meta = meta
+        @reason = reason
+        @retry_after = retry_after
       end
 
       def success?
-        @success
+        @status == :success
+      end
+
+      def deferred?
+        @status == :deferred
       end
 
       def failure?
-        !success?
+        @status == :failure
       end
 
       def self.success(payload:, http_status: :ok, response_effects: nil, meta: {})
-        new(success: true, payload:, errors: [], http_status:, response_effects:, meta:)
+        new(status: :success, payload:, errors: [], http_status:, response_effects:, meta:)
       end
 
       def self.failure(errors:, http_status:, response_effects: nil, meta: {})
-        new(success: false, payload: nil, errors:, http_status:, response_effects:, meta:)
+        new(status: :failure, payload: nil, errors:, http_status:, response_effects:, meta:)
+      end
+
+      def self.deferred(reason:, retry_after:, payload: {}, http_status: :accepted, response_effects: nil, meta: {})
+        new(
+          status: :deferred,
+          payload:,
+          errors: [],
+          http_status:,
+          response_effects:,
+          meta:,
+          reason: reason.to_sym,
+          retry_after: Integer(retry_after)
+        )
       end
     end
   end

data/config/routes.rb

@@ -11,6 +11,8 @@ CommandTower::Engine.routes.draw do
   namespace :auth do
     post "logout", to: "logout#create"
     get "session", to: "session#show"
+    get "principal-capabilities", to: "principal_capabilities#show"
+    delete "impersonation-session", to: "impersonation_session#destroy"
 
     constraints(->(_req) { CommandTower.config.login.plain_text.enable? }) do
       scope path: "plain-text", module: "plain_text" do
@@ -74,6 +76,10 @@ CommandTower::Engine.routes.draw do
       end
     end
 
+    get "audit-events/filter-options", to: "audit_events#filter_options"
+    get "audit-events", to: "audit_events#index"
+    get "audit-events/:id", to: "audit_events#show"
+
     resource :preferences, only: [:show], controller: "preferences"
     patch "preferences/:notification_type_key", to: "preferences#update"
 
@@ -96,6 +102,20 @@ CommandTower::Engine.routes.draw do
   end
 
   namespace :admin do
+    get "audit-events/filter-options", to: "audit/events#filter_options"
+    get "audit-events", to: "audit/events#index"
+    get "audit-events/:id", to: "audit/events#show"
+    get "users", to: "users#index"
+    get "users/assignable-roles", to: "users/roles#index"
+    get "users/:id", to: "users#show"
+    patch "users/:id/name", to: "users/identities#update_name"
+    patch "users/:id/username", to: "users/identities#update_username"
+    patch "users/:id/email", to: "users/identities#update_email"
+    patch "users/:id/email-validation", to: "users/identities#update_email_validation"
+    patch "users/:id/roles", to: "users/roles#update"
+    post "users/:id/impersonation-sessions", to: "users/impersonation_sessions#create"
+    get "workspace", to: "workspace#show"
+
     namespace :messaging do
       post "announcements", to: "announcements#create"
     end

data/db/migrate/20260816000001_create_command_tower_audit_events.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class CreateCommandTowerAuditEvents < ActiveRecord::Migration[7.2]
+  def change
+    create_table :command_tower_audit_events, charset: "utf8mb4", collation: "utf8mb4_0900_ai_ci" do |t|
+      t.string :event_uuid, null: false
+      t.string :action, null: false
+      t.datetime :occurred_at, null: false
+
+      t.string :execution_uuid
+      t.string :correlation_id
+      t.string :request_id
+      t.string :causation_id
+      t.string :source
+
+      t.bigint :actor_user_id
+      t.bigint :affected_user_id
+      t.bigint :effective_user_id
+      t.bigint :originating_administrator_id
+      t.boolean :impersonation_active, null: false, default: false
+      t.string :attribution_mode, null: false
+
+      t.string :subject_type
+      t.bigint :subject_id
+      t.string :subject_label
+
+      t.json :change_set, null: false
+      t.json :metadata, null: false
+
+      t.boolean :user_history, null: false
+      t.json :sensitive_fields, null: false
+      t.string :retention, null: false
+
+      t.timestamps
+    end
+
+    add_index :command_tower_audit_events, :event_uuid, unique: true, name: "index_ct_audit_events_on_event_uuid"
+    add_index :command_tower_audit_events, %i[affected_user_id occurred_at], name: "index_ct_audit_events_on_affected_occurred"
+    add_index :command_tower_audit_events, %i[actor_user_id occurred_at], name: "index_ct_audit_events_on_actor_occurred"
+    add_index :command_tower_audit_events, %i[action occurred_at], name: "index_ct_audit_events_on_action_occurred"
+    add_index :command_tower_audit_events, :execution_uuid, name: "index_ct_audit_events_on_execution_uuid"
+    add_index :command_tower_audit_events, :correlation_id, name: "index_ct_audit_events_on_correlation_id"
+    add_index :command_tower_audit_events, %i[originating_administrator_id occurred_at], name: "index_ct_audit_events_on_originating_admin_occurred"
+  end
+end

data/db/migrate/20260817000001_add_scope_columns_to_command_tower_audit_events.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class AddScopeColumnsToCommandTowerAuditEvents < ActiveRecord::Migration[7.2]
+  def up
+    change_table :command_tower_audit_events, bulk: true do |t|
+      t.string :scope_class, null: false, default: "legacy"
+      t.string :host_context_type
+      t.string :host_context_identifier
+    end
+
+    execute <<~SQL.squish
+      UPDATE command_tower_audit_events
+      SET scope_class = 'legacy'
+      WHERE scope_class IS NULL OR scope_class = 'legacy'
+    SQL
+
+    add_index :command_tower_audit_events,
+      %i[host_context_type host_context_identifier occurred_at],
+      name: "index_ct_audit_events_on_host_context_occurred"
+    add_index :command_tower_audit_events,
+      %i[scope_class occurred_at],
+      name: "index_ct_audit_events_on_scope_class_occurred"
+  end
+
+  def down
+    change_table :command_tower_audit_events, bulk: true do |t|
+      t.remove_index name: "index_ct_audit_events_on_host_context_occurred"
+      t.remove_index name: "index_ct_audit_events_on_scope_class_occurred"
+      t.remove :scope_class
+      t.remove :host_context_type
+      t.remove :host_context_identifier
+    end
+  end
+end

data/db/migrate/20260817000003_create_command_tower_impersonation_sessions.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class CreateCommandTowerImpersonationSessions < ActiveRecord::Migration[7.2]
+  def change
+    create_table :command_tower_impersonation_sessions, id: { type: :string, limit: 36 } do |t|
+      t.bigint :actor_user_id, null: false
+      t.bigint :target_user_id, null: false
+      t.datetime :started_at, null: false
+      t.datetime :last_activity_at, null: false
+      t.datetime :absolute_expires_at, null: false
+      t.datetime :idle_expires_at, null: false
+        t.datetime :ended_at
+        t.string :end_reason, limit: 32
+        t.timestamps
+      end
+
+      add_index :command_tower_impersonation_sessions, :actor_user_id
+      add_index :command_tower_impersonation_sessions, :target_user_id
+      add_index :command_tower_impersonation_sessions,
+        %i[actor_user_id ended_at],
+        name: "index_ct_impersonation_sessions_on_actor_ended"
+
+      add_foreign_key :command_tower_impersonation_sessions, :users, column: :actor_user_id
+      add_foreign_key :command_tower_impersonation_sessions, :users, column: :target_user_id
+    end
+end