command_tower 0.10.0 → 0.11.1

data/lib/command_tower/configuration/registry/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "class_composer"
+require "command_tower/configuration/registry/audit/config"
+require "command_tower/configuration/registry/admin_workspace/config"
+require "command_tower/configuration/registry/principal_capabilities/config"
+
+module CommandTower
+  module Configuration
+    module Registry
+      class Config
+        include ClassComposer::Generator
+
+        add_composer :audit,
+          desc: "Registered semantic audit event policy (CommandTower-owned and host-owned names)",
+          allowed: Audit::Config,
+          dynamic_default: ->(_) { Audit::Config.new },
+          default_shown: "Audit::Config.new"
+
+        add_composer :admin_workspace,
+          desc: "Registered Admin Workspace tools (CommandTower-owned and host-owned)",
+          allowed: AdminWorkspace::Config,
+          dynamic_default: ->(_) { AdminWorkspace::Config.new },
+          default_shown: "AdminWorkspace::Config.new"
+
+        add_composer :principal_capabilities,
+          desc: "Curated frontend-projectable principal capabilities (CommandTower-owned and host-owned)",
+          allowed: PrincipalCapabilities::Config,
+          dynamic_default: ->(_) { PrincipalCapabilities::Config.new },
+          default_shown: "PrincipalCapabilities::Config.new"
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/registry/principal_capabilities/capability_definition.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module PrincipalCapabilities
+        class CapabilityDefinition
+          include ClassComposer::Generator
+
+          add_composer :required_entity,
+            desc: "RBAC entity name required for this principal capability to appear in the projection " \
+                  "(defaults to the capability id when omitted)",
+            allowed: [String, Symbol],
+            default: ""
+
+          attr_accessor :owner, :id
+
+          def validate_definition!(name:)
+            self.id = name.to_s
+            self.owner = owner&.to_sym || :host
+            entity = required_entity.to_s.strip
+            entity = name.to_s if entity.empty?
+            self.required_entity = require_segment!(entity, field: "required_entity", name:)
+          end
+
+          private
+
+          def require_segment!(value, field:, name:)
+            token = value.to_s.strip
+            unless token.match?(CommandTower::Events::SEGMENT)
+              raise CommandTower::PrincipalCapabilities::InvalidCapabilityDefinitionError,
+                "principal capability #{name} has invalid #{field} #{value.inspect}"
+            end
+
+            token
+          end
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/registry/principal_capabilities/config.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "command_tower/principal_capabilities"
+require "command_tower/configuration/registry/principal_capabilities/capability_definition"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module PrincipalCapabilities
+        class Config
+          # Curated CT-owned frontend-projectable capabilities (1:1 entity names).
+          # Deliberate registration only — never an automatic Entity.entities dump.
+          PLATFORM_CAPABILITIES = %i[
+            admin_workspace
+            admin_audit_events
+            admin_messaging_announcements
+            admin_users
+            admin_users_update
+            admin_rbac_assignments
+            admin_impersonation
+            me_audit_events
+          ].freeze
+
+          def initialize
+            @definitions = {}
+            @finalized = false
+            seed_platform_capabilities!
+          end
+
+          def capability(name, owner: :host)
+            raise CommandTower::PrincipalCapabilities::FrozenRegistryError,
+              "principal capabilities registry is frozen" if @finalized
+
+            normalized = normalize_name!(name)
+            existing = @definitions[normalized]
+            if existing
+              if existing.owner == :command_tower && owner == :host
+                raise CommandTower::PrincipalCapabilities::HostOverrideError,
+                  "host cannot redefine CommandTower-owned principal capability #{normalized}"
+              end
+
+              raise CommandTower::PrincipalCapabilities::DuplicateCapabilityError,
+                "principal capability #{normalized} is already registered"
+            end
+
+            definition = CapabilityDefinition.new
+            yield definition if block_given?
+            definition.owner = owner
+            definition.validate_definition!(name: normalized)
+            @definitions[normalized] = definition
+            definition
+          end
+
+          def fetch(name)
+            normalized = normalize_name!(name)
+            definition = @definitions[normalized]
+            if definition.nil?
+              raise CommandTower::PrincipalCapabilities::UnregisteredCapabilityError,
+                "principal capability #{normalized} is not registered"
+            end
+
+            definition
+          end
+
+          def registered?(name)
+            @definitions.key?(normalize_name!(name))
+          rescue CommandTower::PrincipalCapabilities::InvalidCapabilityNameError
+            false
+          end
+
+          def definitions
+            @definitions.dup.freeze
+          end
+
+          def finalize!
+            @definitions.each_value do |definition|
+              next unless definition.respond_to?(:class_composer_freeze_objects!)
+
+              definition.class_composer_freeze_objects!(behavior: :raise, children: true)
+            end
+            @definitions.freeze
+            @finalized = true
+            self
+          end
+
+          def finalized?
+            @finalized
+          end
+
+          def validate_required_entities!(entities)
+            missing = @definitions.filter_map do |name, definition|
+              next if entities.key?(definition.required_entity)
+
+              "#{name} requires #{definition.required_entity}"
+            end
+            return self if missing.empty?
+
+            raise CommandTower::PrincipalCapabilities::MissingRequiredEntityError,
+              "principal capabilities reference unknown RBAC entities: #{missing.join(", ")}"
+          end
+
+          def reset_host_definitions!
+            thaw_for_test!
+            @definitions.delete_if { |_name, definition| definition.owner == :host }
+            self
+          end
+
+          private
+
+          def seed_platform_capabilities!
+            PLATFORM_CAPABILITIES.each do |name|
+              capability(name, owner: :command_tower)
+            end
+          end
+
+          def thaw_for_test!
+            return unless @finalized || @definitions.frozen?
+
+            @definitions = @definitions.dup
+            @finalized = false
+          end
+
+          def normalize_name!(name)
+            token = name.to_s.strip
+            unless token.match?(CommandTower::Events::SEGMENT)
+              raise CommandTower::PrincipalCapabilities::InvalidCapabilityNameError,
+                "invalid principal capability name #{name.inspect}"
+            end
+
+            token
+          end
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/current.rb

@@ -2,6 +2,18 @@
 
 module CommandTower
   class Current < ActiveSupport::CurrentAttributes
+    attribute :execution_uuid
+    attribute :correlation_id
     attribute :request_id
+    attribute :causation_id
+    attribute :source
+    attribute :user_id
+    attribute :originating_administrator_id
+    attribute :effective_user_id
+    attribute :impersonation_active, default: false
+    attribute :impersonation_session_id
+    attribute :impersonation_activity_recorded, default: false
+    attribute :remote_ip
+    attribute :user_agent
   end
 end

data/lib/command_tower/engine.rb

@@ -7,6 +7,8 @@ module CommandTower
   class Engine < ::Rails::Engine
     isolate_namespace CommandTower
 
+    paths.add "app/shared_sequences", eager_load: true
+
     # Run after Rails loads the initializes and environment files
     # Ensures User has already set their desired config before we lock this down
     config.after_initialize do
@@ -22,6 +24,11 @@ module CommandTower
         CommandTower::CredentialResolution::SmtpActionMailerBridge.apply!
 
         unless Rails.env.test?
+          CommandTower.config.impersonation.validate!
+          CommandTower.config.registry.audit.finalize!
+          CommandTower.config.registry.admin_workspace.finalize!
+          CommandTower.config.registry.principal_capabilities.finalize!
+          CommandTower.config.admin_scope.finalize!
           # Now that we can confirm all variables are defined, freeze all objects an their children
           CommandTower.config.class_composer_freeze_objects!(behavior: :raise, children: true)
         end
@@ -46,11 +53,19 @@ module CommandTower
     # Add all RBAC based role definitions prior to fork/loading
     # Load once use forever
     config.to_prepare do
-      CommandTower::Authorization::Role.roles_reset!
-      CommandTower::Authorization::Entity.entities_reset!
-      CommandTower::Authorization.mapped_controllers_reset!
+      skip_composition_validation = defined?(Rake) && (Rake.application.top_level_tasks.any? { |task|
+        task =~ /db:|install:migrations|command_tower:install\z|command_tower:doctor/
+      } rescue nil)
 
-      CommandTower::Authorization.default_defined!
+      CommandTower::Authorization.default_defined!(validate: !skip_composition_validation)
+      unless skip_composition_validation
+        entities = CommandTower::Authorization::Entity.entities
+        CommandTower.config.registry.admin_workspace.validate_required_entities!(entities)
+        CommandTower.config.registry.principal_capabilities.validate_required_entities!(entities)
+        CommandTower.config.admin_scope.validate_scoped_tools!
+      end
+      CommandTower::Logging::Subscriber.attach!
+      CommandTower::Audit::Persistence::Subscriber.attach! unless skip_composition_validation
     end
   end
 end

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