command_tower 0.4.0 → 0.11.0

data/lib/command_tower/admin_scope/scope_option.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    ScopeOption = Data.define(:value, :label)
+  end
+end

data/lib/command_tower/admin_scope.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    class Error < CommandTower::Error; end
+
+    class UnregisteredToolError < Error; end
+    class DuplicateRegistrationError < Error; end
+    class InvalidToolRegistrationError < Error; end
+    class MissingRegistrationError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end
+
+require "command_tower/admin_scope/scope_context"
+require "command_tower/admin_scope/scope_option"
+require "command_tower/admin_scope/resolve"
+require "command_tower/admin_scope/apply_users_narrowing"
+require "command_tower/admin_scope/apply_audit_scoping"
+require "command_tower/admin_scope/manifest_projection"

data/lib/command_tower/admin_workspace.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminWorkspace
+    class Error < CommandTower::Error; end
+
+    class UnregisteredToolError < Error; end
+    class DuplicateToolError < Error; end
+    class HostOverrideError < Error; end
+    class InvalidToolNameError < Error; end
+    class InvalidToolDefinitionError < Error; end
+    class DuplicateRouteError < Error; end
+    class MissingRequiredEntityError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end

data/lib/command_tower/audit/attribution.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    module Attribution
+      MODES = %i[self_service admin_direct impersonation system].freeze
+
+      module_function
+
+      def resolve(affected_user_id:, attribution_mode:)
+        requested = normalize_mode(attribution_mode)
+        impersonating = CommandTower::Current.impersonation_active == true
+
+        if impersonating
+          if requested && requested != :impersonation
+            raise InvalidAttributionError,
+              "attribution_mode #{requested} conflicts with active impersonation"
+          end
+
+          originating = CommandTower::Current.originating_administrator_id
+          if originating.nil?
+            raise InvalidAttributionError, "impersonation requires originating_administrator_id"
+          end
+
+          return envelope(
+            mode: :impersonation,
+            actor_user_id: originating,
+            affected_user_id:
+          )
+        end
+
+        if requested == :impersonation
+          raise InvalidAttributionError, "attribution_mode impersonation requires impersonation_active"
+        end
+
+        if requested == :system || (requested.nil? && CommandTower::Current.user_id.nil?)
+          return envelope(mode: :system, actor_user_id: nil, affected_user_id:)
+        end
+
+        if requested == :admin_direct
+          if CommandTower::Current.user_id.nil?
+            raise InvalidAttributionError, "admin_direct requires a Current.user_id actor"
+          end
+
+          return envelope(mode: :admin_direct, actor_user_id: CommandTower::Current.user_id, affected_user_id:)
+        end
+
+        actor_id = CommandTower::Current.user_id
+        if actor_id.nil?
+          raise InvalidAttributionError, "self_service requires a Current.user_id actor"
+        end
+
+        if requested.nil? && !affected_user_id.nil? && actor_id != affected_user_id
+          raise InvalidAttributionError,
+            "attribution_mode must be explicit when actor and affected user differ"
+        end
+
+        if requested == :self_service && !affected_user_id.nil? && actor_id != affected_user_id
+          raise InvalidAttributionError,
+            "self_service requires Current.user_id to match affected_user_id"
+        end
+
+        envelope(mode: :self_service, actor_user_id: actor_id, affected_user_id:)
+      end
+
+      def normalize_mode(value)
+        return nil if value.nil?
+
+        mode = value.to_sym
+        unless MODES.include?(mode)
+          raise InvalidAttributionError, "invalid attribution_mode #{value.inspect}"
+        end
+
+        mode
+      end
+
+      def envelope(mode:, actor_user_id:, affected_user_id:)
+        {
+          attribution_mode: mode,
+          actor_user_id:,
+          affected_user_id:,
+          effective_user_id: CommandTower::Current.effective_user_id || CommandTower::Current.user_id,
+          originating_administrator_id: CommandTower::Current.originating_administrator_id,
+          impersonation_active: CommandTower::Current.impersonation_active == true,
+          user_id: CommandTower::Current.user_id
+        }
+      end
+    end
+  end
+end

data/lib/command_tower/audit/emit.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "command_tower/audit/attribution"
+require "command_tower/audit/payload"
+
+module CommandTower
+  module Audit
+    module Emit
+      module_function
+
+      def call(name:, subject: nil, affected_user: nil, changes: {}, metadata: {}, attribution_mode: nil, subject_label: nil, scope_class: :global, host_context: nil)
+        registry_name = normalized_event_name(name)
+        definition = CommandTower.config.registry.audit.fetch(registry_name)
+        return nil unless definition.enabled?
+
+        assert_subject!(definition, subject)
+        affected_user_id = extract_user_id(affected_user, required: definition.affected_user_required)
+        validated_changes = Payload.validate_changes!(changes || {}, allowed_keys: definition.allowed_changes)
+        validated_metadata = Payload.validate_metadata!(metadata)
+        attribution = Attribution.resolve(affected_user_id:, attribution_mode:)
+        snapshot = subject_snapshot(subject, subject_label)
+        normalized_scope_class = normalize_scope_class!(scope_class)
+        host_context_fields = normalize_host_context!(host_context, scope_class: normalized_scope_class)
+
+        CommandTower::Events.publish_audit(
+          name: registry_name,
+          envelope: attribution.merge(snapshot).merge(host_context_fields).merge(
+            action: registry_name,
+            occurred_at: Time.now.utc.iso8601(6),
+            scope_class: normalized_scope_class,
+            changes: validated_changes,
+            metadata: validated_metadata
+          )
+        )
+      end
+
+      def normalized_event_name(name)
+        CommandTower.config.registry.audit.fetch(name)
+        name.to_s.split(".").map { |segment| CommandTower::Events.normalize_segment(segment, field: "name") }.join(".")
+      end
+
+      def assert_subject!(definition, subject)
+        return unless definition.subject_required
+        return unless subject.nil?
+
+        raise MissingSubjectError, "audit event requires a subject"
+      end
+
+      def extract_user_id(value, required:)
+        if value.nil?
+          raise MissingAffectedUserError, "audit event requires an affected user" if required
+
+          return nil
+        end
+
+        return value if value.is_a?(Integer)
+        return value.id if value.respond_to?(:id)
+
+        raise InvalidPayloadError, "affected_user must be a user or id"
+      end
+
+      def subject_snapshot(subject, subject_label)
+        label = subject_label.nil? ? nil : subject_label.to_s
+        if subject.nil?
+          return { subject_type: nil, subject_id: nil, subject_label: label }
+        end
+
+        unless subject.respond_to?(:id)
+          raise InvalidPayloadError, "subject must provide an id"
+        end
+
+        {
+          subject_type: subject.class.name,
+          subject_id: subject.id,
+          subject_label: label
+        }
+      end
+
+      def normalize_scope_class!(value)
+        token = value.to_sym
+        normalized = CommandTower::Audit::Event::SCOPE_CLASSES[token]
+        unless normalized
+          raise InvalidPayloadError,
+            "scope_class must be one of #{CommandTower::Audit::Event::SCOPE_CLASSES.keys.join(", ")}"
+        end
+
+        normalized
+      end
+
+      def normalize_host_context!(host_context, scope_class:)
+        host_scope = CommandTower::Audit::Event::SCOPE_CLASSES[:host]
+        if scope_class != host_scope
+          return { host_context_type: nil, host_context_identifier: nil }
+        end
+
+        unless host_context.is_a?(Hash)
+          raise InvalidPayloadError, "host_context is required when scope_class is host"
+        end
+
+        context_type = host_context[:type] || host_context["type"]
+        context_identifier = host_context[:identifier] || host_context["identifier"]
+        if context_type.to_s.strip.empty? || context_identifier.to_s.strip.empty?
+          raise InvalidPayloadError, "host_context requires type and identifier when scope_class is host"
+        end
+
+        {
+          host_context_type: context_type.to_s.strip,
+          host_context_identifier: context_identifier.to_s.strip
+        }
+      end
+    end
+  end
+end

data/lib/command_tower/audit/masking.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    module Masking
+      REDACTED = "********"
+
+      module_function
+
+      def value(field:, raw:)
+        return if raw.nil?
+        return REDACTED unless scalar?(raw)
+
+        string = raw.to_s
+        case field.to_s
+        when "phone" then phone(string)
+        when "email" then email(string)
+        else REDACTED
+        end
+      end
+
+      def phone(string)
+        digits = string.gsub(/\D/, "")
+        return REDACTED if digits.length < 4
+
+        "#{'*' * 7}#{digits[-4, 4]}"
+      end
+
+      def email(string)
+        local, domain = string.split("@", 2)
+        return REDACTED if local.blank? || domain.blank?
+
+        "#{local[0]}***@#{domain}"
+      end
+
+      def scalar?(raw)
+        raw.is_a?(String) || raw.is_a?(Numeric)
+      end
+    end
+  end
+end

data/lib/command_tower/audit/payload.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CommandTower
+  module Audit
+    module Payload
+      SCALAR_TYPES = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol].freeze
+      MAX_DEPTH = 4
+      MAX_BYTES = 16_384
+      CHANGE_KEYS = %w[from to].freeze
+
+      module_function
+
+      def validate!(value, depth: 0, path: "payload")
+        if depth > MAX_DEPTH
+          raise InvalidPayloadError, "#{path} exceeds max nesting depth #{MAX_DEPTH}"
+        end
+
+        case value
+        when Hash
+          value.each do |key, nested|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise InvalidPayloadError, "#{path} has a non-string key #{key.inspect}"
+            end
+
+            validate!(nested, depth: depth + 1, path: "#{path}.#{key}")
+          end
+        when Array
+          value.each_with_index do |item, index|
+            validate!(item, depth: depth + 1, path: "#{path}[#{index}]")
+          end
+        else
+          unless SCALAR_TYPES.any? { |type| value.is_a?(type) }
+            raise InvalidPayloadError, "#{path} contains unsafe type #{value.class}"
+          end
+        end
+
+        value
+      end
+
+      def validate_changes!(changes, allowed_keys:)
+        unless changes.nil? || changes.is_a?(Hash)
+          raise InvalidPayloadError, "changes must be a Hash"
+        end
+
+        normalized = {}
+        (changes || {}).each do |key, value|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise InvalidPayloadError, "changes has a non-string key #{key.inspect}"
+          end
+
+          token = key.to_s
+          unless token.match?(CommandTower::Events::SEGMENT)
+            raise InvalidPayloadError, "changes key #{key.inspect} is invalid"
+          end
+
+          unless allowed_keys.map(&:to_s).include?(token)
+            raise ForbiddenChangeKeyError,
+              "changes key #{token} is not allowed (allowed: #{allowed_keys.join(", ").presence || "none"})"
+          end
+
+          unless value.is_a?(Hash)
+            raise InvalidPayloadError, "changes.#{token} must be a Hash with from/to"
+          end
+
+          extra = value.keys.map(&:to_s) - CHANGE_KEYS
+          if extra.any? || (value.keys.map(&:to_s) & CHANGE_KEYS).empty?
+            raise InvalidPayloadError, "changes.#{token} must use from/to keys only"
+          end
+
+          from_value = value.key?(:from) ? value[:from] : value["from"]
+          to_value = value.key?(:to) ? value[:to] : value["to"]
+          validate!(from_value, depth: 2, path: "changes.#{token}.from")
+          validate!(to_value, depth: 2, path: "changes.#{token}.to")
+          normalized[token] = { "from" => from_value, "to" => to_value }
+        end
+
+        enforce_size!(normalized)
+        normalized
+      end
+
+      def validate_metadata!(metadata)
+        unless metadata.nil? || metadata.is_a?(Hash)
+          raise InvalidPayloadError, "metadata must be a Hash"
+        end
+
+        validated = metadata || {}
+        validate!(validated, path: "metadata")
+        enforce_size!(validated)
+        stringify_keys(validated)
+      end
+
+      def enforce_size!(value)
+        encoded = JSON.generate(jsonify(value))
+        return if encoded.bytesize <= MAX_BYTES
+
+        raise InvalidPayloadError, "audit payload exceeds #{MAX_BYTES} bytes"
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), memo|
+            memo[key.to_s] = stringify_keys(nested)
+          end
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
+      end
+
+      def jsonify(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), memo| memo[key.to_s] = jsonify(nested) }
+        when Array
+          value.map { |item| jsonify(item) }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/audit/persistence/subscriber.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    module Persistence
+      class Subscriber
+        PATTERN = /\Acommand_tower\.audit(?:\.|\z)/
+
+        class << self
+          def attach!
+            detach!
+            subscriber = new
+            @subscriptions = [
+              ActiveSupport::Notifications.subscribe(PATTERN) do |name, started, finished, id, payload|
+                event = ActiveSupport::Notifications::Event.new(name, started, finished, id, payload)
+                subscriber.call(event)
+              end
+            ]
+          end
+
+          def detach!
+            Array(@subscriptions).each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+            @subscriptions = []
+          end
+
+          def subscriptions
+            Array(@subscriptions)
+          end
+        end
+
+        def call(event)
+          payload = event.payload.to_h.with_indifferent_access
+          return unless persistable?(payload)
+
+          persist!(payload)
+        end
+
+        private
+
+        def persistable?(payload)
+          payload[:action].present? && payload[:event_uuid].present?
+        end
+
+        def persist!(payload)
+          action = payload.fetch(:action).to_s
+          definition = CommandTower.config.registry.audit.fetch(action)
+
+          CommandTower::Audit::Event.create!(
+            event_uuid: payload.fetch(:event_uuid),
+            action: action,
+            occurred_at: parse_occurred_at(payload.fetch(:occurred_at)),
+            scope_class: payload.fetch(:scope_class).to_s,
+            host_context_type: payload[:host_context_type],
+            host_context_identifier: payload[:host_context_identifier],
+            execution_uuid: payload[:execution_uuid],
+            correlation_id: payload[:correlation_id],
+            request_id: payload[:request_id],
+            causation_id: payload[:causation_id],
+            source: payload[:source]&.to_s,
+            actor_user_id: payload[:actor_user_id],
+            affected_user_id: payload[:affected_user_id],
+            effective_user_id: payload[:effective_user_id],
+            originating_administrator_id: payload[:originating_administrator_id],
+            impersonation_active: payload[:impersonation_active] == true,
+            attribution_mode: payload.fetch(:attribution_mode).to_s,
+            subject_type: payload[:subject_type],
+            subject_id: payload[:subject_id],
+            subject_label: payload[:subject_label],
+            change_set: payload[:changes] || {},
+            metadata: payload[:metadata] || {},
+            user_history: definition.user_history,
+            sensitive_fields: Array(definition.sensitive_fields).map(&:to_s),
+            retention: definition.retention.to_s
+          )
+        end
+
+        def parse_occurred_at(value)
+          return value if value.is_a?(Time) || value.is_a?(ActiveSupport::TimeWithZone)
+
+          Time.iso8601(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/audit.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    class Error < CommandTower::Error; end
+
+    class UnregisteredEventError < Error; end
+    class DuplicateEventError < Error; end
+    class HostOverrideError < Error; end
+    class InvalidEventNameError < Error; end
+    class ForbiddenChangeKeyError < Error; end
+    class InvalidPayloadError < Error; end
+    class InvalidAttributionError < Error; end
+    class MissingSubjectError < Error; end
+    class MissingAffectedUserError < Error; end
+    class FrozenRegistryError < Error; end
+    class InvalidEventDefinitionError < Error; end
+    class EnablementNotConfigurableError < Error; end
+    class ImmutableError < Error; end
+  end
+end
+
+require "command_tower/audit/payload"
+require "command_tower/audit/attribution"
+require "command_tower/audit/emit"
+require "command_tower/audit/masking"
+require "command_tower/audit/persistence/subscriber"

data/lib/command_tower/authorization/assignable_roles.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Authorization
+    module AssignableRoles
+      OWNER_NAME = "owner"
+
+      module_function
+
+      def catalog
+        CommandTower::Authorization::Role.roles.values
+          .select { |role| assignable?(role) }
+          .sort_by { |role| role.name.to_s }
+          .map do |role|
+            { name: role.name.to_s, description: role.description.to_s }
+          end
+      end
+
+      def names
+        catalog.map { |entry| entry[:name] }.to_set
+      end
+
+      def assignable?(role)
+        return false if role.nil?
+        return false if role.allow_everything
+        return false if role.name.to_s == OWNER_NAME
+
+        role.source == :host
+      end
+
+      def assignable_name?(name)
+        names.include?(name.to_s)
+      end
+    end
+  end
+end