command_tower 0.10.0 → 0.11.0

data/app/jobs/command_tower/execution/job_boundary.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Execution
+    module JobBoundary
+      extend ActiveSupport::Concern
+
+      included do
+        around_perform :command_tower_job_execution
+      end
+
+      private
+
+      def command_tower_job_execution
+        CommandTower.with_execution(source: :job) { yield }
+      end
+    end
+  end
+end

data/app/mailers/command_tower/application_mailer.rb

@@ -2,7 +2,17 @@
 
 module CommandTower
   class ApplicationMailer < ActionMailer::Base
-    default from: "from@example.com"
+    FALLBACK_FROM = "from@example.com"
+
+    default from: -> { smtp_from_address }
     layout "mailer"
+
+    def self.smtp_from_address
+      CredentialResolution.resolve(:smtp).user_name.presence || FALLBACK_FROM
+    end
+
+    def smtp_from_address
+      self.class.smtp_from_address
+    end
   end
 end

data/app/mailers/command_tower/messaging/channel_mailer.rb

@@ -8,8 +8,7 @@ module CommandTower
           raise ArgumentError, "rendered must be a RenderedPayload"
         end
 
-        from_address = CredentialResolution.resolve(:smtp).user_name.presence
-        from_address ||= "from@example.com"
+        from_address = smtp_from_address
 
         mail(
           to: rendered.recipient_address,

data/app/models/command_tower/audit/event.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    class Event < CommandTower::ApplicationRecord
+      self.table_name = "command_tower_audit_events"
+
+      ATTRIBUTION_MODES = %w[self_service admin_direct impersonation system].freeze
+      SCOPE_CLASSES = {
+        global: "global",
+        host: "host",
+        legacy: "legacy"
+      }.freeze
+
+      validates :event_uuid, :action, :occurred_at, :attribution_mode, :scope_class, presence: true
+      validates :attribution_mode, inclusion: { in: ATTRIBUTION_MODES }
+      validates :scope_class, inclusion: { in: SCOPE_CLASSES.values }
+      validates :originating_administrator_id, presence: true, if: :impersonation_active?
+
+      after_initialize do
+        write_attribute(:change_set, {}) if has_attribute?(:change_set) && read_attribute(:change_set).nil?
+        write_attribute(:metadata, {}) if has_attribute?(:metadata) && read_attribute(:metadata).nil?
+        write_attribute(:sensitive_fields, []) if has_attribute?(:sensitive_fields) && read_attribute(:sensitive_fields).nil?
+      end
+
+      before_update :reject_mutation
+      before_destroy :reject_mutation
+
+      private
+
+      def reject_mutation
+        raise ImmutableError, "audit events are append-only"
+      end
+    end
+  end
+end

data/app/models/command_tower/impersonation/session.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Impersonation
+    class Session < CommandTower::ApplicationRecord
+      self.table_name = "command_tower_impersonation_sessions"
+
+      END_REASONS = %w[manual idle_timeout absolute_timeout logout revoked].freeze
+
+      belongs_to :actor, class_name: "User", foreign_key: :actor_user_id
+      belongs_to :target, class_name: "User", foreign_key: :target_user_id
+
+      before_create :assign_public_id
+
+      validates :actor_user_id, :target_user_id, :started_at, :last_activity_at,
+        :absolute_expires_at, :idle_expires_at, presence: true
+      validates :end_reason, inclusion: { in: END_REASONS }, allow_nil: true
+
+      scope :open, -> { where(ended_at: nil) }
+
+      def open?
+        ended_at.nil?
+      end
+
+      def idle_expired?(at: Time.current)
+        idle_expires_at <= at
+      end
+
+      def absolutely_expired?(at: Time.current)
+        absolute_expires_at <= at
+      end
+
+      def expired?(at: Time.current)
+        idle_expired?(at:) || absolutely_expired?(at:)
+      end
+
+      def expiration_reason(at: Time.current)
+        return "absolute_timeout" if absolutely_expired?(at:)
+        return "idle_timeout" if idle_expired?(at:)
+
+        nil
+      end
+
+      private
+
+      def assign_public_id
+        self.id = SecureRandom.uuid if id.blank?
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/admin/users.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Admin
+      module Users
+        class UserSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(user)
+            first_name = user.first_name.to_s
+            last_name = user.last_name.to_s
+            full_name = [first_name, last_name].map(&:strip).reject(&:empty?).join(" ")
+            full_name = user.full_name.strip if full_name.empty? && user.respond_to?(:full_name)
+
+            {
+              id: user.id,
+              firstName: first_name,
+              lastName: last_name,
+              fullName: full_name,
+              username: user.username,
+              email: user.email,
+              emailValidated: user.email_validated,
+              phoneNumber: phone_number_for(user),
+              phoneNumberValidated: phone_number_validated_for(user),
+              roles: user.roles,
+              createdAt: user.created_at&.iso8601
+            }
+          end
+
+          def self.phone_number_for(user)
+            return nil unless user.respond_to?(:phone_number)
+
+            user.phone_number.presence
+          end
+          private_class_method :phone_number_for
+
+          def self.phone_number_validated_for(user)
+            return false unless user.respond_to?(:phone_number_validated)
+
+            !!user.phone_number_validated
+          end
+          private_class_method :phone_number_validated_for
+        end
+
+        class PaginationMetaSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(pagination)
+            {
+              limit: pagination.fetch(:limit),
+              offset: pagination.fetch(:offset),
+              totalCount: pagination.fetch(:total_count)
+            }
+          end
+        end
+
+        class AssignableRolesSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(roles)
+            {
+              roles: Array(roles).map do |role|
+                {
+                  name: role.fetch(:name),
+                  description: role.fetch(:description)
+                }
+              end
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/admin/workspace/manifest_serializer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Admin
+      module Workspace
+        class ManifestSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(tools)
+            {
+              tools: Array(tools).map do |tool|
+                payload = {
+                  id: tool.fetch(:id),
+                  label: tool.fetch(:label),
+                  description: tool.fetch(:description),
+                  route: tool.fetch(:route),
+                  group: tool.fetch(:group),
+                  sortOrder: tool.fetch(:sort_order),
+                  icon: tool[:icon]
+                }
+                payload[:scope] = serialize_scope(tool[:scope]) if tool.key?(:scope)
+                payload[:scopeOptions] = serialize_scope_options(tool[:scope_options]) if tool.key?(:scope_options)
+                payload[:availability] = serialize_availability(tool[:availability]) if tool.key?(:availability)
+                payload
+              end
+            }
+          end
+
+          def self.serialize_scope(scope)
+            {
+              required: scope.fetch(:required),
+              parameter: scope.fetch(:parameter),
+              label: scope.fetch(:label)
+            }
+          end
+          private_class_method :serialize_scope
+
+          def self.serialize_scope_options(options)
+            Array(options).map do |option|
+              {
+                value: option.fetch(:value),
+                label: option.fetch(:label)
+              }
+            end
+          end
+          private_class_method :serialize_scope_options
+
+          def self.serialize_availability(availability)
+            {
+              enabled: availability.fetch(:enabled),
+              reason: availability[:reason]
+            }
+          end
+          private_class_method :serialize_availability
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/audit/events/filter_options_serializer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Audit
+      module Events
+        class FilterOptionsSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(event_names:, subject_types:, attribution_modes:)
+            {
+              eventNames: Array(event_names).map { |entry| serialize_event_option(entry) },
+              subjectTypes: Array(subject_types).map { |entry| serialize_subject_option(entry) },
+              attributionModes: Array(attribution_modes).map { |entry| serialize_mode_option(entry) }
+            }
+          end
+
+          def self.serialize_event_option(entry)
+            {
+              value: entry.fetch(:value),
+              label: entry.fetch(:label),
+              tags: Array(entry.fetch(:tags))
+            }
+          end
+          private_class_method :serialize_event_option
+
+          def self.serialize_subject_option(entry)
+            {
+              value: entry.fetch(:value),
+              label: entry.fetch(:label)
+            }
+          end
+          private_class_method :serialize_subject_option
+
+          def self.serialize_mode_option(entry)
+            {
+              value: entry.fetch(:value),
+              label: entry.fetch(:label)
+            }
+          end
+          private_class_method :serialize_mode_option
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Audit
+      module Events
+        class EventSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(projection)
+            {
+              id: projection.fetch(:id),
+              eventName: projection.fetch(:event_name),
+              eventLabel: projection.fetch(:event_label),
+              occurredAt: iso8601(projection.fetch(:occurred_at)),
+              attributionMode: projection.fetch(:attribution_mode),
+              actor: { userId: projection[:actor_user_id] },
+              affectedUser: { userId: projection[:affected_user_id] },
+              subject: {
+                type: projection[:subject_type],
+                id: projection[:subject_id],
+                label: projection[:subject_label]
+              },
+              impersonationActive: projection.fetch(:impersonation_active),
+              originatingAdministratorId: projection[:originating_administrator_id],
+              changes: projection.fetch(:changes),
+              metadata: projection.fetch(:metadata)
+            }
+          end
+        end
+
+        class PaginationMetaSerializer < CommandTower::Serializers::ApplicationSerializer
+          def self.serialize(pagination)
+            {
+              limit: pagination.fetch(:limit),
+              offset: pagination.fetch(:offset),
+              totalCount: pagination.fetch(:total_count)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/principal_capabilities_serializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Auth
+      class PrincipalCapabilitiesSerializer
+        def self.serialize(principal_capability_ids)
+          {
+            principalCapabilities: Array(principal_capability_ids).map(&:to_s)
+          }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/auth/session_response_serializer.rb

@@ -4,12 +4,36 @@ module CommandTower
   module Serializers
     module Auth
       class SessionResponseSerializer
-        def self.serialize(user:, token_expires_at:)
-          {
+        def self.serialize(user:, token_expires_at:, impersonation_session: nil, actor: nil)
+          payload = {
             user: CommandTower::Serializers::Auth::UserSerializer.serialize(user),
             tokenExpiresAt: token_expires_at
           }
+          return payload if impersonation_session.nil?
+
+          actor_user = actor || impersonation_session.actor
+          payload[:impersonation] = {
+            active: true,
+            sessionId: impersonation_session.id,
+            actorUserId: impersonation_session.actor_user_id,
+            actorDisplayName: display_name(actor_user),
+            targetUserId: impersonation_session.target_user_id,
+            idleExpiresAt: CommandTower::Serializers::ApplicationSerializer.iso8601(
+              impersonation_session.idle_expires_at
+            ),
+            absoluteExpiresAt: CommandTower::Serializers::ApplicationSerializer.iso8601(
+              impersonation_session.absolute_expires_at
+            )
+          }
+          payload
+        end
+
+        def self.display_name(user)
+          return nil if user.nil?
+
+          [user.first_name, user.last_name].compact_blank.join(" ").presence || user.username
         end
+        private_class_method :display_name
       end
     end
   end

data/app/serializers/command_tower/serializers/impersonation/session_serializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Impersonation
+      class SessionSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(session)
+          {
+            id: session.id,
+            actorUserId: session.actor_user_id,
+            targetUserId: session.target_user_id,
+            idleExpiresAt: iso8601(session.idle_expires_at),
+            absoluteExpiresAt: iso8601(session.absolute_expires_at)
+          }
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/README.md

@@ -17,16 +17,10 @@ All services in CommandTower that use this pattern inherit `CommandTower::Servic
 ## What does ServiceBase offer
 
 ### Logging
-`ServiceBase` offers a convenient way to tag logs. It keeps track of:
-- The start of the logic call
-- The time it took to complete the logic
-- The status of the logic
-
-Additionally, it provides some convenience methods for logging
-- `log_debug`
-- `log_info`
-- `log_warn`
-- `log_error`
+
+Lifecycle logging is an `ActiveSupport::Notifications` consumer. Services do not write Start/Finished lines to `Rails.logger`.
+
+Operational notes from services still use `log_info` / `log_warn` / `log_error`, which publish `command_tower.log.*` events. See [Eventing](../../../docs/eventing.md).
 
 ### Argument Validation
 Argument Validation is the powerhouse behind ServiceBase

data/app/services/command_tower/authorize/validate.rb

@@ -46,21 +46,24 @@ module CommandTower::Authorize
 
     def call
       unless authorization_required?
-        log_info("controller:#{controller}; method:#{action} -- No Authorization required")
+        log_debug("controller:#{controller}; method:#{action} -- No Authorization required")
         return Decision.authorized(user:, authorization_required: false, msg: NOT_REQUIRED_MSG)
       end
 
       # At this point we know authorization on the route is required
       # Iterate through the users roles to find a matching role that allows authorization
       # If at least 1 of the users roles passes validation, we can allow access to the path
-      log_info("User Roles: #{user.roles}")
+      log_debug("User Roles: #{user.roles}")
       authorized = user_role_objects.any? do |_role_name, role_object|
         result = role_object.authorized?(controller:, method: action, user:)
-        log_info("Role:#{result[:role]};Authorized:[#{result[:authorized]}];Reason:[#{result[:reason]}]")
+        log_debug("Role:#{result[:role]};Authorized:[#{result[:authorized]}];Reason:[#{result[:reason]}]")
         result[:authorized] == true
       end
 
-      return Decision.denied(user:, msg: UNAUTHORIZED_MSG) unless authorized
+      unless authorized
+        log_warn("controller:#{controller}; method:#{action} -- #{UNAUTHORIZED_MSG}")
+        return Decision.denied(user:, msg: UNAUTHORIZED_MSG)
+      end
 
       Decision.authorized(user:, authorization_required: true, msg: AUTHORIZED_MSG)
     end

data/app/services/command_tower/jwt/authenticate_user.rb

@@ -45,12 +45,18 @@ module CommandTower::Jwt
       end
 
       generated_token = nil
+      impersonation_session_id = payload[:impersonation_session_id].presence
       if with_reset
-        generated_token = LoginCreate.(user:).token
+        generated_token = LoginCreate.(user:, impersonation_session_id:).token
         expires_at = CommandTower.config.jwt.ttl.from_now.to_time
       end
 
-      AuthenticationOutcome.success(user:, expires_at: expires_at.to_s, generated_token:)
+      AuthenticationOutcome.success(
+        user:,
+        expires_at: expires_at.to_s,
+        generated_token:,
+        impersonation_session_id:
+      )
     end
 
     private

data/app/services/command_tower/jwt/authentication_outcome.rb

@@ -4,10 +4,10 @@ module CommandTower::Jwt
   # Narrow value object describing the result of AuthenticateUser only.
   # This is deliberately not a platform result type — do not reuse it elsewhere.
   class AuthenticationOutcome
-    attr_reader :user, :expires_at, :generated_token, :status, :msg
+    attr_reader :user, :expires_at, :generated_token, :status, :msg, :impersonation_session_id
 
-    def self.success(user:, expires_at:, generated_token: nil)
-      new(success: true, user:, expires_at:, generated_token:)
+    def self.success(user:, expires_at:, generated_token: nil, impersonation_session_id: nil)
+      new(success: true, user:, expires_at:, generated_token:, impersonation_session_id:)
     end
 
     # `user` is carried on failures so callers can distinguish a known user who
@@ -16,13 +16,14 @@ module CommandTower::Jwt
       new(success: false, msg:, status:, user:)
     end
 
-    def initialize(success:, user: nil, expires_at: nil, generated_token: nil, status: nil, msg: nil)
+    def initialize(success:, user: nil, expires_at: nil, generated_token: nil, status: nil, msg: nil, impersonation_session_id: nil)
       @success = success
       @user = user
       @expires_at = expires_at
       @generated_token = generated_token
       @status = status
       @msg = msg
+      @impersonation_session_id = impersonation_session_id
     end
 
     def success?

data/app/services/command_tower/jwt/login_create.rb

@@ -4,16 +4,19 @@ module CommandTower::Jwt
   class LoginCreate
     IssuedToken = Data.define(:token)
 
-    def self.call(user:)
-      IssuedToken.new(token: Encode.(payload: payload_for(user)))
+    def self.call(user:, impersonation_session_id: nil)
+      IssuedToken.new(token: Encode.(payload: payload_for(user, impersonation_session_id:)))
     end
 
-    def self.payload_for(user)
-      {
+    def self.payload_for(user, impersonation_session_id: nil)
+      payload = {
         generated_at: Time.now.to_i,
         user_id: user.id,
         verifier_token: user.retreive_verifier_token!,
       }
+      token = impersonation_session_id.to_s.strip
+      payload[:impersonation_session_id] = token unless token.empty?
+      payload
     end
     private_class_method :payload_for
   end

data/app/services/command_tower/messaging/accept/operation_logger.rb

@@ -18,7 +18,7 @@ module CommandTower
               ),
             }
 
-            Contract::Observability::StructuredLogger.info(
+            Contract::Observability::Publisher.info(
               base.merge(event: "messaging.accept.started"),
             )
 
@@ -31,7 +31,7 @@ module CommandTower
                 "messaging.accept.succeeded"
               end
 
-            Contract::Observability::StructuredLogger.info(
+            Contract::Observability::Publisher.info(
               base.merge(
                 event:,
                 duration_ms: elapsed_ms(started_at),
@@ -62,7 +62,7 @@ module CommandTower
           private
 
           def log_failure(base, started_at, error, level, error_code, event)
-            Contract::Observability::StructuredLogger.public_send(
+            Contract::Observability::Publisher.public_send(
               level,
               base.merge(
                 event:,

data/app/services/command_tower/messaging/contract/observability/correlation.rb

@@ -8,7 +8,9 @@ module CommandTower
           module_function
 
           def resolve
-            CommandTower::Current.request_id.presence || SecureRandom.uuid
+            CommandTower::Current.correlation_id.presence ||
+              CommandTower::Current.request_id.presence ||
+              SecureRandom.uuid
           end
         end
       end

data/app/services/command_tower/messaging/contract/observability/operation_logger.rb

@@ -14,13 +14,13 @@ module CommandTower
                 messaging_operation: operation,
               }.merge(request_fields(request))
 
-              StructuredLogger.info(
+              Publisher.info(
                 base.merge(event: "messaging.#{operation}.started"),
               )
 
               result = yield
 
-              StructuredLogger.info(
+              Publisher.info(
                 base.merge(
                   event: "messaging.#{operation}.succeeded",
                   duration_ms: elapsed_ms(started_at),
@@ -45,7 +45,7 @@ module CommandTower
             private
 
             def log_failure(base, started_at, operation, error, level, error_code)
-              StructuredLogger.public_send(
+              Publisher.public_send(
                 level,
                 base.merge(
                   event: "messaging.#{operation}.failed",

data/app/services/command_tower/messaging/contract/observability/publisher.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Contract
+      module Observability
+        class Publisher
+          FORBIDDEN_KEYS = %i[title body text metadata email password token].freeze
+
+          class << self
+            def info(payload = nil, **kwargs)
+              emit(:info, payload || kwargs)
+            end
+
+            def warn(payload = nil, **kwargs)
+              emit(:warn, payload || kwargs)
+            end
+
+            def error(payload = nil, **kwargs)
+              emit(:error, payload || kwargs)
+            end
+
+            def emit(level, payload)
+              hash = payload.respond_to?(:to_h) ? payload.to_h : {}
+              event = hash[:event] || hash["event"]
+              raise ArgumentError, "messaging event name required" if event.blank?
+
+              name = event.to_s.sub(/\Amessaging\./, "")
+              extra = {}
+              hash.each do |key, value|
+                next if key.to_s == "event"
+
+                extra[key.to_sym] = value
+              end
+              FORBIDDEN_KEYS.each { |key| extra.delete(key) }
+              extra[:log_level] = level
+              CommandTower::Events.publish(category: :messaging, name:, payload: extra)
+            end
+          end
+        end
+      end
+    end
+  end
+end