command_tower 0.4.0 → 0.11.0

data/lib/command_tower/events.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Events
+    PREFIX = "command_tower"
+    SEGMENT = /\A[a-z][a-z0-9_]*\z/
+    SNAPSHOT_KEYS = %i[
+      execution_uuid
+      correlation_id
+      request_id
+      causation_id
+      source
+      user_id
+      originating_administrator_id
+      effective_user_id
+      impersonation_active
+    ].freeze
+    SCALAR_TYPES = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol].freeze
+
+    WORKFLOW_STARTED = "command_tower.lifecycle.workflow.started"
+    WORKFLOW_COMPLETED = "command_tower.lifecycle.workflow.completed"
+    SERVICE_STARTED = "command_tower.lifecycle.service.started"
+    SERVICE_COMPLETED = "command_tower.lifecycle.service.completed"
+
+    module_function
+
+    def instrument_name(category:, name:)
+      category_segment = normalize_segment(category, field: "category")
+      name_segments = name.to_s.split(".")
+      raise ArgumentError, "name must contain at least one segment" if name_segments.empty?
+
+      normalized_name = name_segments.map { |segment| normalize_segment(segment, field: "name") }
+      "#{PREFIX}.#{category_segment}.#{normalized_name.join(".")}"
+    end
+
+    def snapshot
+      SNAPSHOT_KEYS.each_with_object({}) do |key, memo|
+        memo[key] = CommandTower::Current.public_send(key)
+      end.freeze
+    end
+
+    def publish(category:, name:, payload: {}, subject: nil, layer: nil)
+      event_payload = snapshot.merge(event_uuid: SecureRandom.uuid)
+      event_payload[:subject] = subject if subject
+      event_payload[:layer] = layer if layer
+      event_payload.merge!(sanitize_payload(payload))
+      ActiveSupport::Notifications.instrument(instrument_name(category:, name:), event_payload.freeze)
+    end
+
+    def publish_audit(name:, envelope:)
+      raise CommandTower::Audit::InvalidPayloadError, "audit envelope must be a Hash" unless envelope.is_a?(Hash)
+
+      CommandTower::Audit::Payload.validate!(envelope[:changes] || {}, path: "changes")
+      CommandTower::Audit::Payload.validate!(envelope[:metadata] || {}, path: "metadata")
+      CommandTower::Audit::Payload.enforce_size!(envelope)
+
+      event_payload = snapshot.merge(
+        event_uuid: SecureRandom.uuid,
+        action: name.to_s,
+        occurred_at: envelope[:occurred_at] || Time.now.utc.iso8601(6)
+      )
+      %i[
+        actor_user_id
+        affected_user_id
+        effective_user_id
+        originating_administrator_id
+        impersonation_active
+        attribution_mode
+        subject_type
+        subject_id
+        subject_label
+        user_id
+        scope_class
+        host_context_type
+        host_context_identifier
+        changes
+        metadata
+      ].each do |key|
+        event_payload[key] = envelope[key] if envelope.key?(key)
+      end
+
+      ActiveSupport::Notifications.instrument(instrument_name(category: :audit, name:), event_payload.freeze)
+    end
+
+    def publish_lifecycle(layer:, phase:, subject:, outcome: nil, duration_ms: nil, error_class: nil, error_codes: nil, log_level: nil, log_lifecycle: false)
+      extra = {}
+      extra[:outcome] = outcome if phase == :completed
+      extra[:duration_ms] = duration_ms if phase == :completed && !duration_ms.nil?
+      extra[:error_class] = error_class if error_class
+      extra[:error_codes] = error_codes if error_codes
+      extra[:log_level] = log_level if log_level
+      extra[:log_lifecycle] = log_lifecycle ? true : false
+      publish(
+        category: :lifecycle,
+        name: "#{layer}.#{phase}",
+        payload: extra,
+        subject:,
+        layer:
+      )
+    end
+
+    def around_execution(layer:, subject:, log_lifecycle: false)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      publish_lifecycle(layer:, phase: :started, subject:, log_lifecycle:)
+      record = { result: nil, unexpected: nil, error_codes: nil, log_level: nil }
+      begin
+        yield record
+      ensure
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+        publish_lifecycle(
+          layer:,
+          phase: :completed,
+          subject:,
+          outcome: outcome_for(layer:, record:),
+          duration_ms:,
+          error_class: record[:unexpected]&.class&.name,
+          error_codes: error_codes_for(record),
+          log_level: log_level_for(record),
+          log_lifecycle:
+        )
+      end
+      record[:result]
+    end
+
+    def outcome_for(layer:, record:)
+      return :error if record[:unexpected]
+
+      result = record[:result]
+      return result if layer == :service && %i[success failure].include?(result)
+      return :success if result.respond_to?(:success?) && result.success?
+      return :deferred if result.respond_to?(:deferred?) && result.deferred?
+      return :failure if result.respond_to?(:failure?) && result.failure?
+
+      :error
+    end
+
+    def error_codes_for(record)
+      return record[:error_codes] if record[:error_codes]
+      return nil unless record[:result].respond_to?(:errors)
+
+      codes = Array(record[:result].errors).filter_map { |error| error.code if error.respond_to?(:code) }
+      codes.empty? ? nil : codes
+    end
+
+    def log_level_for(record)
+      return :error if record[:unexpected]
+      return record[:log_level] if record[:log_level]
+      return nil unless record[:result].respond_to?(:errors)
+
+      Array(record[:result].errors).filter_map { |error| error.log_level if error.respond_to?(:log_level) }.first
+    end
+
+    def sanitize_payload(payload)
+      raise ArgumentError, "payload must be a Hash" unless payload.nil? || payload.is_a?(Hash)
+
+      (payload || {}).each_with_object({}) do |(key, value), memo|
+        next unless scalar_key?(key)
+        next unless scalar_value?(value)
+
+        memo[key.to_sym] = value
+      end
+    end
+
+    def normalize_segment(value, field:)
+      segment = value.to_s
+      unless segment.match?(SEGMENT)
+        raise ArgumentError, "invalid #{field} segment #{value.inspect}"
+      end
+
+      segment
+    end
+
+    def scalar_key?(key)
+      key.is_a?(String) || key.is_a?(Symbol)
+    end
+
+    def scalar_value?(value)
+      return true if SCALAR_TYPES.any? { |type| value.is_a?(type) }
+      return false unless value.is_a?(Array)
+
+      value.all? { |item| SCALAR_TYPES.any? { |type| item.is_a?(type) } }
+    end
+  end
+end

data/lib/command_tower/execution.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Execution
+    SOURCES = %i[http job rake console].freeze
+
+    module ContextAccess
+      def execution_context
+        CommandTower::Current
+      end
+
+      def publish_event(category:, name:, payload: {})
+        CommandTower::Events.publish(category:, name:, payload:, subject: self.class.name)
+      end
+
+      def audit(name, subject: nil, affected_user: nil, changes: {}, metadata: {}, attribution_mode: nil, subject_label: nil, scope_class: :global, host_context: nil)
+        CommandTower::Audit::Emit.call(
+          name:,
+          subject:,
+          affected_user:,
+          changes:,
+          metadata:,
+          attribution_mode:,
+          subject_label:,
+          scope_class:,
+          host_context:
+        )
+      end
+
+      def log_debug(msg)
+        publish_event(category: :log, name: :debug, payload: { message: msg.to_s })
+      end
+
+      def log_info(msg)
+        publish_event(category: :log, name: :info, payload: { message: msg.to_s })
+      end
+
+      def log_warn(msg)
+        publish_event(category: :log, name: :warn, payload: { message: msg.to_s })
+      end
+
+      def log_error(msg)
+        publish_event(category: :log, name: :error, payload: { message: msg.to_s })
+      end
+    end
+
+    module IdentityEnrichment
+      module_function
+
+      def from_user(user)
+        return if user.nil?
+
+        CommandTower::Current.user_id = user.id
+        CommandTower::Current.effective_user_id = user.id
+        CommandTower::Current.originating_administrator_id = nil
+        CommandTower::Current.impersonation_active = false
+        CommandTower::Current.impersonation_session_id = nil
+      end
+
+      def from_impersonation_session(session, actor:, target:)
+        CommandTower::Current.user_id = target.id
+        CommandTower::Current.effective_user_id = target.id
+        CommandTower::Current.originating_administrator_id = actor.id
+        CommandTower::Current.impersonation_active = true
+        CommandTower::Current.impersonation_session_id = session.id
+      end
+    end
+  end
+
+  def self.with_execution(source:, **attrs, &block)
+    raise ArgumentError, "block required" unless block
+
+    source = source.to_sym
+    unless Execution::SOURCES.include?(source)
+      raise ArgumentError, "invalid execution source #{source.inspect} (allowed: #{Execution::SOURCES.join(", ")})"
+    end
+
+    return yield if Current.execution_uuid.present?
+
+    execution_uuid = attrs[:execution_uuid].presence || SecureRandom.uuid
+    assigned = {
+      execution_uuid:,
+      correlation_id: attrs[:correlation_id].presence || execution_uuid,
+      source:,
+      request_id: attrs[:request_id],
+      causation_id: attrs[:causation_id],
+      user_id: attrs[:user_id],
+      originating_administrator_id: attrs[:originating_administrator_id],
+      effective_user_id: attrs[:effective_user_id],
+      impersonation_active: attrs.key?(:impersonation_active) ? attrs[:impersonation_active] : false,
+      impersonation_session_id: attrs[:impersonation_session_id],
+      impersonation_activity_recorded: attrs.key?(:impersonation_activity_recorded) ? attrs[:impersonation_activity_recorded] : false,
+      remote_ip: attrs[:remote_ip],
+      user_agent: attrs[:user_agent]
+    }
+
+    run = -> { Current.set(assigned, &block) }
+
+    if execution_wrapper_idle?
+      Rails.application.executor.wrap { run.call }
+    else
+      run.call
+    end
+  end
+
+  def self.execution_wrapper_idle?
+    return true unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+    !Rails.application.executor.active?
+  end
+end

data/lib/command_tower/impersonation/activity_declaration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Impersonation
+    module ActivityDeclaration
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def impersonation_activity!
+          @impersonation_activity = true
+        end
+
+        def impersonation_activity?
+          return @impersonation_activity unless @impersonation_activity.nil?
+
+          superclass.respond_to?(:impersonation_activity?) ? superclass.impersonation_activity? : false
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/impersonation/apply_overlay.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Impersonation
+    Overlay = Data.define(:actor, :target, :session, :status)
+
+    module ApplyOverlay
+      module_function
+
+      def call(actor:, session_id:, mode: :enforce)
+        token = session_id.to_s.strip
+        return Overlay.new(actor:, target: actor, session: nil, status: :none) if token.empty?
+
+        session = CommandTower::Impersonation::Session.find_by(id: token)
+        if session.nil? || session.actor_user_id != actor.id
+          return reject_or_none(actor:, session: nil, mode:)
+        end
+
+        unless session.open?
+          return reject_or_none(actor:, session:, mode:)
+        end
+
+        if session.expired?
+          return expire_open_session(actor:, session:, mode:)
+        end
+
+        target = User.find_by(id: session.target_user_id)
+        if target.nil?
+          ended = end_session(session, reason: "revoked", actor:)
+          emit_ended(ended, reason: "revoked") if ended
+          return reject_or_none(actor:, session: session.reload, mode:)
+        end
+
+        Overlay.new(actor:, target:, session:, status: :active)
+      end
+
+      def reject_or_none(actor:, session:, mode:)
+        if mode.to_sym == :enforce
+          return Overlay.new(actor:, target: actor, session:, status: :expired)
+        end
+
+        Overlay.new(actor:, target: actor, session:, status: :none)
+      end
+      private_class_method :reject_or_none
+
+      def expire_open_session(actor:, session:, mode:)
+        reason = session.expiration_reason
+        if mode.to_sym == :enforce
+          ended = end_session(session, reason:, actor:)
+          emit_ended(ended, reason:) if ended
+          return Overlay.new(actor:, target: actor, session: session.reload, status: :expired)
+        end
+
+        Overlay.new(actor:, target: actor, session:, status: :stale)
+      end
+      private_class_method :expire_open_session
+
+      def end_session(session, reason:, actor:)
+        result = CommandTower::Services::Impersonation::End.call(
+          session_id: session.id,
+          reason:,
+          actor_user_id: actor.id
+        )
+        return unless result.success? && result.data[:ended]
+
+        result.data[:session]
+      end
+      private_class_method :end_session
+
+      def emit_ended(session, reason:)
+        target = User.find_by(id: session.target_user_id)
+        return if target.nil?
+
+        CommandTower::Impersonation::ClearOverlayForAudit.call(actor_user_id: session.actor_user_id) do
+          CommandTower::Audit::Emit.call(
+            name: :impersonation_ended,
+            subject: target,
+            affected_user: target,
+            changes: { reason: { from: nil, to: reason } },
+            metadata: { impersonation_session_id: session.id },
+            attribution_mode: :admin_direct
+          )
+        end
+      end
+      private_class_method :emit_ended
+    end
+  end
+end

data/lib/command_tower/impersonation/clear_overlay_for_audit.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Impersonation
+    # Temporarily clear overlay identity so impersonation_ended audits attribute
+    # as admin_direct to the actor. Lives outside workflows/services so leaf
+    # layers do not establish Current execution boundaries themselves.
+    module ClearOverlayForAudit
+      module_function
+
+      def call(actor_user_id:)
+        CommandTower::Current.set(
+          user_id: actor_user_id,
+          effective_user_id: actor_user_id,
+          originating_administrator_id: nil,
+          impersonation_active: false
+        ) do
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/impersonation/establish_identity.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Impersonation
+    EstablishedIdentity = Data.define(:user, :actor, :session, :status) do
+      def expired?
+        status == :expired
+      end
+
+      def active?
+        status == :active
+      end
+    end
+
+    module EstablishIdentity
+      module_function
+
+      def call(actor:, impersonation_session_id:, mode: :enforce)
+        overlay = ApplyOverlay.call(actor:, session_id: impersonation_session_id, mode:)
+        if overlay.status == :expired && mode.to_sym == :enforce
+          CommandTower::Execution::IdentityEnrichment.from_user(actor)
+          return EstablishedIdentity.new(user: actor, actor:, session: overlay.session, status: :expired)
+        end
+
+        if overlay.status == :active
+          CommandTower::Execution::IdentityEnrichment.from_impersonation_session(
+            overlay.session,
+            actor: overlay.actor,
+            target: overlay.target
+          )
+          return EstablishedIdentity.new(
+            user: overlay.target,
+            actor: overlay.actor,
+            session: overlay.session,
+            status: :active
+          )
+        end
+
+        CommandTower::Execution::IdentityEnrichment.from_user(actor)
+        EstablishedIdentity.new(user: actor, actor:, session: overlay.session, status: overlay.status)
+      end
+    end
+  end
+end

data/lib/command_tower/install/baseline.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Install
+    # Compact final-schema baseline authored in CommandTower (Phase 5.2).
+    # Hosts receive copies via Rails-native `command_tower:install:migrations`.
+    module Baseline
+      ENGINE_MIGRATION_BASENAMES = %w[
+        20260805000001_create_command_tower_users.rb
+        20260805000002_create_command_tower_user_secrets.rb
+        20260805000003_create_command_tower_messaging_core.rb
+        20260805000004_create_messaging_notification_preferences.rb
+        20260805000005_create_messaging_endpoints_and_pushover_credentials.rb
+        20260816000001_create_command_tower_audit_events.rb
+        20260817000001_add_scope_columns_to_command_tower_audit_events.rb
+        20260817000003_create_command_tower_impersonation_sessions.rb
+      ].freeze
+
+      module_function
+
+      def migrate_dir
+        CommandTower::Engine.root.join("db/migrate")
+      end
+
+      def engine_migration_basenames
+        Dir.children(migrate_dir).grep(/\.rb\z/).sort
+      end
+
+      def host_installed_migrations(host_root = Rails.root)
+        Dir.glob(File.join(host_root.to_s, "db/migrate", "*command_tower*.rb")).map { |p| File.basename(p) }.sort
+      end
+    end
+  end
+end