command_tower 0.10.0 → 0.11.1

data/lib/command_tower/authorization.rb

@@ -5,6 +5,8 @@ require "set"
 require "command_tower/error"
 require "command_tower/authorization/entity"
 require "command_tower/authorization/role"
+require "command_tower/authorization/effective_entity_grants"
+require "command_tower/authorization/assignable_roles"
 
 module CommandTower
   module Authorization
@@ -12,6 +14,9 @@ module CommandTower
 
     class Error < CommandTower::Error; end
 
+    SOURCE_COMMAND_TOWER = :command_tower
+    SOURCE_HOST = :host
+
     def mapped_controllers
       @mapped_controllers ||= {}
     end
@@ -27,21 +32,29 @@ module CommandTower
       @mapped_controllers = {}
     end
 
-    def default_defined!
+    def reset_graph!
+      CommandTower::Authorization::Role.roles_reset!
+      CommandTower::Authorization::Entity.entities_reset!
+      mapped_controllers_reset!
+    end
+
+    def default_defined!(validate: true)
+      reset_graph!
       provision_rbac_default!
       provision_rbac_user_defined!
+      validate_composed_graph! if validate
     end
 
     def provision_rbac_user_defined!
       path = CommandTower.config.authorization.rbac_group_path
       rbac_configuration = load_yaml(path)
-      provision_rbac_via_yaml(rbac_configuration)
+      provision_rbac_via_yaml(rbac_configuration, source: SOURCE_HOST)
     end
 
     def provision_rbac_default!
       path = CommandTower::Engine.root.join("lib", "command_tower", "authorization", "default.yml")
       rbac_configuration = load_yaml(path)
-      provision_rbac_via_yaml(rbac_configuration)
+      provision_rbac_via_yaml(rbac_configuration, source: SOURCE_COMMAND_TOWER)
     end
 
     def load_yaml(path)
@@ -50,27 +63,56 @@ module CommandTower
       YAML.load_file(path)
     end
 
-    def provision_rbac_via_yaml(rbac_configuration)
+    def provision_rbac_via_yaml(rbac_configuration, source:)
       return if rbac_configuration.nil?
 
-      rbac_configuration["entities"].each do |entity|
+      unless rbac_configuration.is_a?(Hash)
+        raise Error, "RBAC source must be a mapping (got #{rbac_configuration.class})"
+      end
+
+      entity_rows = rbac_configuration["entities"]
+      if !entity_rows.nil? && !entity_rows.is_a?(Array)
+        raise Error, "RBAC entities must be a list"
+      end
+
+      Array(entity_rows).each do |entity|
+        raise Error, "RBAC entity definition must be a mapping" unless entity.is_a?(Hash)
+        raise Error, "RBAC entity is missing name" if entity["name"].blank?
+
         CommandTower::Authorization::Entity.create_entity(
           name: entity["name"],
           controller: entity["controller"],
           only: entity["only"],
           except: entity["except"],
+          source: source,
         )
       end
 
-      rbac_configuration["groups"].each do |name, metadata|
-        entities = nil
-        allow_everything = false
+      groups = rbac_configuration["groups"]
+      return if groups.nil?
+
+      unless groups.is_a?(Hash)
+        raise Error, "RBAC groups must be a mapping"
+      end
+
+      groups.each do |name, metadata|
+        raise Error, "RBAC group [#{name}] must be a mapping" unless metadata.is_a?(Hash)
+
         description = metadata["description"]
+        allow_everything = false
+        entities = nil
 
         if metadata["entities"] == true
-          allow_everything =  true
+          allow_everything = true
         else
-          entities = CommandTower::Authorization::Entity.entities.map { |k, v| v if metadata["entities"].include?(k) }.compact
+          grant_names = Array(metadata["entities"])
+          entities = grant_names.map do |grant_name|
+            resolved = CommandTower::Authorization::Entity.entities[grant_name]
+            if resolved.nil?
+              raise Error, "RBAC group [#{name}] references unknown entity [#{grant_name}]"
+            end
+            resolved
+          end
         end
 
         CommandTower::Authorization::Role.create_role(
@@ -78,8 +120,27 @@ module CommandTower
           entities:,
           description:,
           allow_everything:,
+          source: source,
         )
       end
     end
+
+    def validate_composed_graph!
+      validate_default_membership_role!
+    end
+
+    def validate_default_membership_role!
+      role_name = CommandTower.config.authorization.default_membership_role
+      return if role_name.nil?
+
+      if role_name.to_s.strip.empty?
+        raise Error, "authorization.default_membership_role is blank; use nil to disable default assignment"
+      end
+
+      return if CommandTower::Authorization::Role.roles[role_name]
+
+      raise Error,
+        "authorization.default_membership_role [#{role_name}] is not present in the composed RBAC graph"
+    end
   end
 end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "command_tower/admin_scope"
+require "command_tower/configuration/admin_scope/tool_registration"
+
+module CommandTower
+  module Configuration
+    module AdminScope
+      class Config
+        def initialize
+          @registrations = {}
+          @finalized = false
+        end
+
+        def register(tool_id, &block)
+          raise CommandTower::AdminScope::FrozenRegistryError, "admin scope registry is frozen" if @finalized
+
+          normalized = normalize_tool_id!(tool_id)
+          if @registrations.key?(normalized)
+            raise CommandTower::AdminScope::DuplicateRegistrationError,
+              "admin scope registration for #{normalized} already exists"
+          end
+
+          registration = ToolRegistration.new
+          yield registration if block_given?
+          registration.validate!(tool_id: normalized)
+          @registrations[normalized] = registration
+          registration
+        end
+
+        def fetch(tool_id)
+          normalized = normalize_tool_id!(tool_id)
+          registration = @registrations[normalized]
+          if registration.nil?
+            raise CommandTower::AdminScope::UnregisteredToolError,
+              "admin scope registration for #{normalized} is not registered"
+          end
+
+          registration
+        end
+
+        def registered?(tool_id)
+          @registrations.key?(normalize_tool_id!(tool_id))
+        rescue CommandTower::AdminWorkspace::InvalidToolNameError
+          false
+        end
+
+        def registrations
+          @registrations.dup.freeze
+        end
+
+        def finalize!
+          @registrations.freeze
+          @finalized = true
+          self
+        end
+
+        def finalized?
+          @finalized
+        end
+
+        def validate_scoped_tools!
+          CommandTower.config.registry.admin_workspace.definitions.each do |tool_id, definition|
+            next unless definition.scope_required?
+
+            unless registered?(tool_id)
+              raise CommandTower::AdminScope::MissingRegistrationError,
+                "admin workspace tool #{tool_id} requires scope but has no admin_scope registration"
+            end
+
+            fetch(tool_id).validate!(tool_id:)
+          end
+          self
+        end
+
+        def reset_registrations!
+          thaw_for_test!
+          @registrations.clear
+          self
+        end
+
+        private
+
+        def normalize_tool_id!(tool_id)
+          CommandTower.config.registry.admin_workspace.fetch(tool_id)
+          token = tool_id.to_s.strip
+          unless token.match?(CommandTower::Events::SEGMENT)
+            raise CommandTower::AdminWorkspace::InvalidToolNameError,
+              "invalid admin scope tool id #{tool_id.inspect}"
+          end
+
+          token
+        end
+
+        def thaw_for_test!
+          return unless @finalized || @registrations.frozen?
+
+          @registrations = @registrations.dup
+          @finalized = false
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/admin_scope/tool_registration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Configuration
+    module AdminScope
+      class ToolRegistration
+        REQUIRED_HOOKS = %i[options validate availability narrow_users narrow_audit affected_users_in_scope].freeze
+
+        attr_accessor :options, :validate, :availability, :narrow_users, :narrow_audit,
+          :affected_users_in_scope, :host_context_type
+
+        def validate!(tool_id:)
+          missing = REQUIRED_HOOKS.reject { |hook| callable?(public_send(hook)) }
+          return self if missing.empty?
+
+          raise CommandTower::AdminScope::InvalidToolRegistrationError,
+            "admin scope registration for #{tool_id} is missing hooks: #{missing.join(", ")}"
+        end
+
+        private
+
+        def callable?(value)
+          value.respond_to?(:call)
+        end
+      end
+    end
+  end
+end

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

@@ -18,6 +18,12 @@ module CommandTower
           allowed: String,
           dynamic_default: ->(_) { Rails.root.join("config","rbac_groups.yml").to_s },
           default_shown: "Rails.root.join(\"config\",\"rbac_groups.yml\")"
+
+        add_composer :default_membership_role,
+          desc: "Optional role name assigned atomically when a user is registered. " \
+                "nil disables assignment. Must exist in the composed RBAC graph at boot.",
+          allowed: [String, NilClass],
+          default: nil
       end
     end
   end

data/lib/command_tower/configuration/config.rb

@@ -3,12 +3,14 @@
 require "singleton"
 require "class_composer"
 require "command_tower/configuration/admin/config"
+require "command_tower/configuration/admin_scope/config"
 require "command_tower/configuration/application/config"
 require "command_tower/configuration/authorization/config"
 require "command_tower/configuration/base"
 require "command_tower/configuration/credentials/config"
 require "command_tower/configuration/email/config"
 require "command_tower/configuration/identity/config"
+require "command_tower/configuration/impersonation/config"
 require "command_tower/configuration/jwt/config"
 require "command_tower/configuration/jwt/cookie/config"
 require "command_tower/configuration/login/config"
@@ -16,6 +18,7 @@ require "command_tower/configuration/messaging/config"
 require "command_tower/configuration/otp/config"
 require "command_tower/configuration/pagination/config"
 require "command_tower/configuration/password_recovery_session/config"
+require "command_tower/configuration/registry/config"
 require "command_tower/configuration/signup_session/config"
 require "command_tower/configuration/user/config"
 require "command_tower/configuration/username/config"
@@ -78,6 +81,11 @@ module CommandTower
         allowed: Configuration::Identity::Config,
         default: Configuration::Identity::Config.new
 
+      add_composer :impersonation,
+        desc: "Impersonation session idle and absolute timeouts",
+        allowed: Configuration::Impersonation::Config,
+        default: Configuration::Impersonation::Config.new
+
       add_composer :messaging,
         desc: "Messaging delivery configuration (notification SMS, etc.). Separate from Identity OTP.",
         allowed: Configuration::Messaging::Config,
@@ -88,11 +96,23 @@ module CommandTower
         allowed: Configuration::Admin::Config,
         default: Configuration::Admin::Config.new
 
+      add_composer :admin_scope,
+        desc: "Host hooks for optional Admin resource scoping (options, validation, narrowing)",
+        allowed: Configuration::AdminScope::Config,
+        dynamic_default: ->(_) { Configuration::AdminScope::Config.new },
+        default_shown: "Configuration::AdminScope::Config.new"
+
       add_composer :pagination,
         desc: "Pagination configuration for the app",
         allowed: Configuration::Pagination::Config,
         default: Configuration::Pagination::Config.new
 
+      add_composer :registry,
+        desc: "Host and platform registrations expressed as configuration (not a plugin API)",
+        allowed: Configuration::Registry::Config,
+        dynamic_default: ->(_) { Configuration::Registry::Config.new },
+        default_shown: "Configuration::Registry::Config.new"
+
       add_composer :signup_session,
         desc: "Signup session token claims, TTL, and signup rate limit ceilings",
         allowed: Configuration::SignupSession::Config,

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "class_composer"
+require "command_tower/configuration/base"
+
+module CommandTower
+  module Configuration
+    module Impersonation
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :idle_timeout,
+          desc: "Idle lifetime of an impersonation session. Successful qualifying workflow execution may extend this clock. HTTP activity alone does not.",
+          allowed: ActiveSupport::Duration,
+          default: 10.minutes
+
+        add_composer :absolute_timeout,
+          desc: "Absolute maximum lifetime of an impersonation session measured from start. Activity never extends this clock.",
+          allowed: ActiveSupport::Duration,
+          default: 1.hour
+
+        def validate!
+          if idle_timeout.nil? || idle_timeout <= 0
+            raise ArgumentError, "config.impersonation.idle_timeout must be a positive duration"
+          end
+          if absolute_timeout.nil? || absolute_timeout <= 0
+            raise ArgumentError, "config.impersonation.absolute_timeout must be a positive duration"
+          end
+          if idle_timeout >= absolute_timeout
+            raise ArgumentError, "config.impersonation.idle_timeout must be less than absolute_timeout"
+          end
+
+          self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "command_tower/admin_workspace"
+require "command_tower/configuration/registry/admin_workspace/tool_definition"
+
+module CommandTower
+  module Configuration
+    module Registry
+      module AdminWorkspace
+        class Config
+          PLATFORM_TOOLS = {
+            users: {
+              label: "Users",
+              description: "Find and inspect platform user accounts.",
+              route: "/admin/users",
+              group: "operations",
+              sort_order: 50,
+              required_entity: "admin_users",
+              icon: "users"
+            },
+            audit: {
+              label: "Audit",
+              description: "Browse account and administrative audit history.",
+              route: "/admin/audit",
+              group: "operations",
+              sort_order: 100,
+              required_entity: "admin_audit_events",
+              icon: "history"
+            },
+            messaging: {
+              label: "Messaging",
+              description: "Manage platform announcements and administrative messaging.",
+              route: "/admin/messaging",
+              group: "messaging",
+              sort_order: 200,
+              required_entity: "admin_messaging_announcements",
+              icon: "megaphone"
+            }
+          }.freeze
+
+          def initialize
+            @definitions = {}
+            @finalized = false
+            seed_platform_tools!
+          end
+
+          def tool(name, owner: :host)
+            raise CommandTower::AdminWorkspace::FrozenRegistryError, "admin workspace registry is frozen" if @finalized
+
+            normalized = normalize_name!(name)
+            existing = @definitions[normalized]
+            if existing
+              if existing.owner == :command_tower && owner == :host
+                raise CommandTower::AdminWorkspace::HostOverrideError,
+                  "host cannot redefine CommandTower-owned admin workspace tool #{normalized}"
+              end
+
+              raise CommandTower::AdminWorkspace::DuplicateToolError,
+                "admin workspace tool #{normalized} is already registered"
+            end
+
+            definition = ToolDefinition.new
+            yield definition if block_given?
+            definition.owner = owner
+            definition.validate_definition!(name: normalized)
+            assert_unique_route!(definition)
+            @definitions[normalized] = definition
+            definition
+          end
+
+          def configure_tool(name)
+            raise CommandTower::AdminWorkspace::FrozenRegistryError, "admin workspace registry is frozen" if @finalized
+
+            normalized = normalize_name!(name)
+            definition = fetch(normalized)
+            if definition.owner != :command_tower
+              raise CommandTower::AdminWorkspace::HostOverrideError,
+                "configure_tool is only for CommandTower-owned admin workspace tools"
+            end
+
+            yield definition
+            definition.validate_definition!(name: normalized)
+            definition
+          end
+
+          def fetch(name)
+            normalized = normalize_name!(name)
+            definition = @definitions[normalized]
+            if definition.nil?
+              raise CommandTower::AdminWorkspace::UnregisteredToolError,
+                "admin workspace tool #{normalized} is not registered"
+            end
+
+            definition
+          end
+
+          def registered?(name)
+            @definitions.key?(normalize_name!(name))
+          rescue CommandTower::AdminWorkspace::InvalidToolNameError
+            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::AdminWorkspace::MissingRequiredEntityError,
+              "admin workspace tools reference unknown RBAC entities: #{missing.join(", ")}"
+          end
+
+          def reset_host_definitions!
+            thaw_for_test!
+            @definitions.delete_if { |_name, definition| definition.owner == :host }
+            restore_platform_tools!
+            self
+          end
+
+          # Spec cleanup: re-seed unfrozen platform tools (scope_required defaults false).
+          # finalize! freezes ToolDefinition composers; thaw alone does not unfreeze them.
+          def reset_platform_tool_scope_config!
+            thaw_for_test!
+            restore_platform_tools!
+            self
+          end
+
+          private
+
+          def seed_platform_tools!
+            PLATFORM_TOOLS.each do |name, attrs|
+              tool(name, owner: :command_tower) do |definition|
+                definition.label = attrs[:label]
+                definition.description = attrs[:description]
+                definition.route = attrs[:route]
+                definition.group = attrs[:group]
+                definition.sort_order = attrs[:sort_order]
+                definition.required_entity = attrs[:required_entity]
+                definition.icon = attrs[:icon]
+              end
+            end
+          end
+
+          def restore_platform_tools!
+            PLATFORM_TOOLS.each_key { |name| @definitions.delete(name.to_s) }
+            seed_platform_tools!
+          end
+
+          def thaw_for_test!
+            return unless @finalized || @definitions.frozen?
+
+            @definitions = @definitions.dup
+            @finalized = false
+          end
+
+          def assert_unique_route!(definition)
+            conflict = @definitions.values.find { |other| other.route == definition.route }
+            return unless conflict
+
+            raise CommandTower::AdminWorkspace::DuplicateRouteError,
+              "admin workspace tool #{definition.id} reuses route #{definition.route} " \
+              "(already registered by #{conflict.id})"
+          end
+
+          def normalize_name!(name)
+            token = name.to_s.strip
+            unless token.match?(CommandTower::Events::SEGMENT)
+              raise CommandTower::AdminWorkspace::InvalidToolNameError,
+                "invalid admin workspace tool name #{name.inspect}"
+            end
+
+            token
+          end
+        end
+      end
+    end
+  end
+end