command_tower 0.10.0 → 0.11.0

data/lib/command_tower/configuration/registry/admin_workspace/tool_definition.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module AdminWorkspace
+        class ToolDefinition
+          include ClassComposer::Generator
+
+          ROUTE = %r{\A/admin(/[a-z][a-z0-9_-]*)+\z}
+
+          DESCRIPTION_MAX_LENGTH = 160
+
+          add_composer :label,
+            desc: "Human-readable tool name for dashboard and navigation",
+            allowed: String,
+            default: ""
+
+          add_composer :description,
+            desc: "Short launcher blurb: what the tool does (presentation only; soft target ≤100 chars)",
+            allowed: String,
+            default: ""
+
+          add_composer :route,
+            desc: "Frontend Admin Workspace path (navigation metadata, not an engine API path)",
+            allowed: String,
+            default: ""
+
+          add_composer :group,
+            desc: "Presentation group token (open set; domain-blind)",
+            allowed: [String, Symbol],
+            default: ""
+
+          add_composer :sort_order,
+            desc: "Order within and across groups (lower first)",
+            allowed: Integer,
+            default: 0
+
+          add_composer :required_entity,
+            desc: "RBAC entity name required for this tool to appear in the manifest",
+            allowed: [String, Symbol],
+            default: ""
+
+          add_composer :icon,
+            desc: "Optional icon token for the shared frontend",
+            allowed: [String, Symbol, NilClass],
+            default: nil
+
+          add_composer :scope_required,
+            desc: "When true, admin requests for this tool require a host scope parameter",
+            allowed: [TrueClass, FalseClass],
+            default: false
+
+          add_composer :scope_parameter,
+            desc: "Transport parameter name for the host scope value (snake_case token)",
+            allowed: String,
+            default: ""
+
+          add_composer :scope_label,
+            desc: "Human-readable label for the scope picker",
+            allowed: String,
+            default: ""
+
+          attr_accessor :owner, :id
+
+          def scope_required?
+            scope_required == true
+          end
+
+          def validate_definition!(name:)
+            self.id = name.to_s
+            self.owner = owner&.to_sym || :host
+            self.label = require_present_string!(label, field: "label", name:)
+            self.description = normalize_description!(name:)
+            self.route = require_route!(name:)
+            self.group = require_segment!(group, field: "group", name:)
+            self.required_entity = require_segment!(required_entity, field: "required_entity", name:)
+            self.icon = normalize_icon!(name:)
+            normalize_scope!(name:)
+            unless sort_order.is_a?(Integer)
+              raise CommandTower::AdminWorkspace::InvalidToolDefinitionError,
+                "admin workspace tool #{name} has invalid sort_order #{sort_order.inspect}"
+            end
+          end
+
+          private
+
+          def normalize_description!(name:)
+            text = description.to_s.strip
+            if text.length > DESCRIPTION_MAX_LENGTH
+              raise CommandTower::AdminWorkspace::InvalidToolDefinitionError,
+                "admin workspace tool #{name} description exceeds #{DESCRIPTION_MAX_LENGTH} characters"
+            end
+
+            text
+          end
+
+          def require_present_string!(value, field:, name:)
+            text = value.to_s.strip
+            if text.empty?
+              raise CommandTower::AdminWorkspace::InvalidToolDefinitionError,
+                "admin workspace tool #{name} is missing #{field}"
+            end
+
+            text
+          end
+
+          def require_route!(name:)
+            path = require_present_string!(route, field: "route", name:)
+            unless path.match?(ROUTE)
+              raise CommandTower::AdminWorkspace::InvalidToolDefinitionError,
+                "admin workspace tool #{name} has invalid route #{path.inspect}"
+            end
+
+            path
+          end
+
+          def require_segment!(value, field:, name:)
+            token = value.to_s.strip
+            unless token.match?(CommandTower::Events::SEGMENT)
+              raise CommandTower::AdminWorkspace::InvalidToolDefinitionError,
+                "admin workspace tool #{name} has invalid #{field} #{value.inspect}"
+            end
+
+            token
+          end
+
+          def normalize_icon!(name:)
+            return if icon.nil? || icon.to_s.strip.empty?
+
+            require_segment!(icon, field: "icon", name:)
+          end
+
+          def normalize_scope!(name:)
+            if scope_required?
+              self.scope_parameter = require_segment!(scope_parameter, field: "scope_parameter", name:)
+              self.scope_label = require_present_string!(scope_label, field: "scope_label", name:)
+              return
+            end
+
+            self.scope_parameter = ""
+            self.scope_label = ""
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require "command_tower/configuration/registry/audit/event_definition"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module Audit
+        class Config
+          PLATFORM_EVENTS = {
+            user_registered: {
+              label: "User registered",
+              tags: %w[identity account registration],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            role_assigned: {
+              label: "Role assigned",
+              tags: %w[identity rbac authorization],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: %i[role],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            role_revoked: {
+              label: "Role revoked",
+              tags: %w[identity rbac authorization],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: %i[role],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            password_changed: {
+              label: "Password changed",
+              tags: %w[identity password security],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            email_verified: {
+              label: "Email verified",
+              tags: %w[identity verification email],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            admin_user_name_changed: {
+              label: "Admin user name changed",
+              tags: %w[identity admin users],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: %i[first_name last_name],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            admin_user_username_changed: {
+              label: "Admin user username changed",
+              tags: %w[identity admin users],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: %i[username],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            admin_user_email_changed: {
+              label: "Admin user email changed",
+              tags: %w[identity admin users email],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            admin_user_email_validation_changed: {
+              label: "Admin user email validation changed",
+              tags: %w[identity admin users verification email],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: %i[email_validated],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            phone_updated: {
+              label: "Phone updated",
+              tags: %w[identity phone profile],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: %i[phone],
+              allowed_changes: %i[phone],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            phone_cleared: {
+              label: "Phone cleared",
+              tags: %w[identity phone profile],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: %i[phone],
+              allowed_changes: %i[phone],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            phone_verified: {
+              label: "Phone verified",
+              tags: %w[identity verification phone],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            announcement_produced: {
+              label: "Announcement produced",
+              tags: %w[messaging announcement admin],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: false,
+              affected_user_required: false
+            },
+            session_created: {
+              label: "Session created",
+              tags: %w[authentication session security],
+              enabled: true,
+              enablement_configurable: true,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :ninety_days,
+              subject_required: false,
+              affected_user_required: true
+            },
+            session_cleared: {
+              label: "Session cleared",
+              tags: %w[authentication session security],
+              enabled: false,
+              enablement_configurable: true,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :ninety_days,
+              subject_required: false,
+              affected_user_required: true
+            },
+            login_failed: {
+              label: "Login failed",
+              tags: %w[authentication login security],
+              enabled: false,
+              enablement_configurable: true,
+              user_history: false,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :ninety_days,
+              subject_required: false,
+              affected_user_required: false
+            },
+            impersonation_started: {
+              label: "Impersonation started",
+              tags: %w[authentication impersonation security],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
+            impersonation_ended: {
+              label: "Impersonation ended",
+              tags: %w[authentication impersonation security],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: %i[reason],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            }
+          }.freeze
+
+          def initialize
+            @definitions = {}
+            @finalized = false
+            seed_platform_events!
+          end
+
+          def event(name, owner: :host)
+            raise CommandTower::Audit::FrozenRegistryError, "audit registry is frozen" if @finalized
+
+            normalized = normalize_name!(name)
+            existing = @definitions[normalized]
+            if existing
+              if existing.owner == :command_tower && owner == :host
+                raise CommandTower::Audit::HostOverrideError,
+                  "host cannot redefine CommandTower-owned audit event #{normalized}"
+              end
+
+              raise CommandTower::Audit::DuplicateEventError,
+                "audit event #{normalized} is already registered"
+            end
+
+            definition = EventDefinition.new
+            yield definition if block_given?
+            definition.owner = owner
+            definition.validate_policy!(name: normalized)
+            @definitions[normalized] = definition
+            definition
+          end
+
+          def set_enabled!(name, value)
+            raise CommandTower::Audit::FrozenRegistryError, "audit registry is frozen" if @finalized
+            unless [true, false].include?(value)
+              raise CommandTower::Audit::InvalidEventDefinitionError, "enabled must be true or false"
+            end
+
+            definition = fetch(name)
+            if definition.owner != :command_tower
+              raise CommandTower::Audit::HostOverrideError,
+                "set_enabled! is only for CommandTower-owned audit events"
+            end
+            unless definition.enablement_configurable?
+              raise CommandTower::Audit::EnablementNotConfigurableError,
+                "audit event #{normalize_name!(name)} enablement is not configurable"
+            end
+
+            definition.enabled = value
+            definition
+          end
+
+          def fetch(name)
+            normalized = normalize_name!(name)
+            definition = @definitions[normalized]
+            if definition.nil?
+              raise CommandTower::Audit::UnregisteredEventError,
+                "audit event #{normalized} is not registered"
+            end
+
+            definition
+          end
+
+          def registered?(name)
+            @definitions.key?(normalize_name!(name))
+          rescue CommandTower::Audit::InvalidEventNameError
+            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 reset_host_definitions!
+            thaw_for_test!
+            @definitions.delete_if { |_name, definition| definition.owner == :host }
+            restore_platform_enablement!
+            self
+          end
+
+          private
+
+          def seed_platform_events!
+            PLATFORM_EVENTS.each do |name, attrs|
+              event(name, owner: :command_tower) do |definition|
+                definition.enabled = attrs[:enabled]
+                definition.enablement_configurable = attrs.fetch(:enablement_configurable, false)
+                definition.user_history = attrs[:user_history]
+                definition.sensitive_fields = attrs[:sensitive_fields]
+                definition.allowed_changes = attrs[:allowed_changes]
+                definition.retention = attrs[:retention]
+                definition.subject_required = attrs[:subject_required]
+                definition.affected_user_required = attrs[:affected_user_required]
+                definition.label = attrs.fetch(:label, "")
+                definition.tags = attrs.fetch(:tags, [])
+                definition.subject_type = attrs.fetch(:subject_type, "")
+                definition.global_visible_in_host_scope = attrs.fetch(:global_visible_in_host_scope, false)
+              end
+            end
+          end
+
+          def restore_platform_enablement!
+            PLATFORM_EVENTS.each_key { |name| @definitions.delete(name.to_s) }
+            seed_platform_events!
+          end
+
+          def thaw_for_test!
+            return unless @finalized || @definitions.frozen?
+
+            @definitions = @definitions.dup
+            @finalized = false
+          end
+
+          def normalize_name!(name)
+            raise CommandTower::Audit::InvalidEventNameError, "audit event name is required" if name.nil? || name.to_s.strip.empty?
+
+            segments = name.to_s.split(".")
+            raise CommandTower::Audit::InvalidEventNameError, "audit event name is required" if segments.empty?
+
+            normalized = segments.map do |segment|
+              unless segment.match?(CommandTower::Events::SEGMENT)
+                raise CommandTower::Audit::InvalidEventNameError,
+                  "invalid audit event name #{name.inspect}"
+              end
+
+              segment
+            end
+
+            normalized.join(".")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/registry/audit/event_definition.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module Audit
+        class EventDefinition
+          include ClassComposer::Generator
+
+          RETENTIONS = %i[permanent ninety_days one_year].freeze
+
+          add_composer :enabled,
+            desc: "When false, audit(...) does not emit a notification",
+            allowed: [TrueClass, FalseClass],
+            default: true
+
+          add_composer :enablement_configurable,
+            desc: "When true, hosts may change only the enabled setting for this CommandTower-owned event",
+            allowed: [TrueClass, FalseClass],
+            default: false
+
+          add_composer :user_history,
+            desc: "Whether this event type may appear in account history (query enforcement is later)",
+            allowed: [TrueClass, FalseClass],
+            default: true
+
+          add_composer :sensitive_fields,
+            desc: "Registered field names that later projections must treat as sensitive",
+            allowed: Array,
+            default: []
+
+          add_composer :allowed_changes,
+            desc: "Allowlisted keys for the runtime changes hash",
+            allowed: Array,
+            default: []
+
+          add_composer :retention,
+            desc: "Retention intent seam (enforcement is later)",
+            allowed: Symbol,
+            default: :permanent
+
+          add_composer :subject_required,
+            desc: "When true, audit(...) must supply a subject",
+            allowed: [TrueClass, FalseClass],
+            default: false
+
+          add_composer :affected_user_required,
+            desc: "When true, audit(...) must supply an affected user",
+            allowed: [TrueClass, FalseClass],
+            default: false
+
+          add_composer :label,
+            desc: "Optional human-readable display label for Explorer UI (empty falls back to event name)",
+            allowed: String,
+            default: ""
+
+          add_composer :tags,
+            desc: "Discovery tags for filter-option selectors (presentation only; not ledger/authz)",
+            allowed: Array,
+            default: []
+
+          add_composer :subject_type,
+            desc: "Optional canonical subject class name for Explorer Resource catalogs (empty = none)",
+            allowed: String,
+            default: ""
+
+          add_composer :global_visible_in_host_scope,
+            desc: "When true, global-scoped events may appear in host-scoped admin audit views for affected users in scope",
+            allowed: [TrueClass, FalseClass],
+            default: false
+
+          attr_accessor :owner
+
+          def enabled?
+            enabled == true
+          end
+
+          def enablement_configurable?
+            enablement_configurable == true
+          end
+
+          def global_visible_in_host_scope?
+            global_visible_in_host_scope == true
+          end
+
+          def validate_policy!(name:)
+            unless RETENTIONS.include?(retention.to_sym)
+              raise CommandTower::Audit::InvalidEventDefinitionError,
+                "audit event #{name} has invalid retention #{retention.inspect} " \
+                "(allowed: #{RETENTIONS.join(", ")})"
+            end
+
+            normalized_allowed = normalize_field_list!(allowed_changes, field: "allowed_changes", name:)
+            normalized_sensitive = normalize_field_list!(sensitive_fields, field: "sensitive_fields", name:)
+            extra_sensitive = normalized_sensitive - normalized_allowed
+            if extra_sensitive.any?
+              raise CommandTower::Audit::InvalidEventDefinitionError,
+                "audit event #{name} sensitive_fields #{extra_sensitive.inspect} " \
+                "must be included in allowed_changes"
+            end
+
+            self.allowed_changes = normalized_allowed
+            self.sensitive_fields = normalized_sensitive
+            self.tags = normalize_tags!(tags, name:)
+            self.subject_type = normalize_subject_type!(subject_type, name:)
+            self.retention = retention.to_sym
+            self.owner = owner&.to_sym || :host
+          end
+
+          def normalize_field_list!(values, field:, name:)
+            Array(values).map do |value|
+              segment = value.to_s
+              unless segment.match?(CommandTower::Events::SEGMENT)
+                raise CommandTower::Audit::InvalidEventDefinitionError,
+                  "audit event #{name} #{field} contains invalid token #{value.inspect}"
+              end
+
+              segment.to_sym
+            end
+          end
+
+          # Lowercase, stripped, unique, deterministic. Rejects blank / invalid tokens.
+          def normalize_tags!(values, name:)
+            Array(values).filter_map do |value|
+              tag = value.to_s.strip.downcase
+              next if tag.empty?
+
+              unless tag.match?(/\A[a-z0-9_]+\z/)
+                raise CommandTower::Audit::InvalidEventDefinitionError,
+                  "audit event #{name} tags contains invalid token #{value.inspect}"
+              end
+
+              tag
+            end.uniq.sort
+          end
+
+          SUBJECT_TYPE = /\A[A-Z][A-Za-z0-9_:]*\z/
+
+          def normalize_subject_type!(value, name:)
+            token = value.to_s.strip
+            return "" if token.empty?
+            unless SUBJECT_TYPE.match?(token)
+              raise CommandTower::Audit::InvalidEventDefinitionError,
+                "audit event #{name} subject_type is invalid #{value.inspect}"
+            end
+
+            token
+          end
+        end
+      end
+    end
+  end
+end