command_tower 0.4.0 → 0.11.0

data/lib/command_tower/authorization/default.yml

@@ -3,40 +3,106 @@ groups:
   owner:
     description: The owner of the application will have full access to all components
     entities: true
-  admin:
-    description: |
-      This group defines permissions for Admin Read and Write operations. Users with this role will have
-      the ability to view and update other users states.
-    entities:
-      - admin
-      - message-blast
-  admin-without-impersonation:
-    description: |
-      This group defines permissions for Admin Read and Write operations. Users with this role will have
-      the ability to view and update other users states. However, impersonation is not permitted with this role
-    entities:
-      - admin-without-impersonate
-      - message-blast
-  admin-read-only:
-    description: |
-      This group defines permissions for Admin Read interface only.
-    entities:
-      - read-admin
-      - message-blast-read-only
 entities:
-  - name: message-blast
-    controller: CommandTower::Inbox::MessageBlastController
-  - name: message-blast-read-only
-    controller: CommandTower::Inbox::MessageBlastController
-    only: metadata
-  - name: read-admin
-    controller: CommandTower::AdminController
+  - name: email_verification_send
+    controller: CommandTower::Auth::EmailVerification::SendController
+    only: create
+  - name: email_verification_verify
+    controller: CommandTower::Auth::EmailVerification::VerifyController
+    only: create
+  - name: session
+    controller: CommandTower::Auth::SessionController
+    only: show
+  - name: me
+    controller: CommandTower::MeController
+    only: show
+  - name: profile
+    controller: CommandTower::ProfileController
+    only: show
+  - name: me_name
+    controller: CommandTower::Me::NameController
+    only: update
+  - name: me_password
+    controller: CommandTower::Me::PasswordController
+    only: update
+  - name: me_inbox
+    controller: CommandTower::Me::InboxController
+    only:
+      - index
+      - show
+      - open
+      - archive
+      - destroy
+      - unread_count
+      - bulk_read
+      - bulk_unread
+      - bulk_archive
+      - bulk_restore
+      - bulk_delete
+  - name: me_preferences
+    controller: CommandTower::Me::PreferencesController
+    only:
+      - show
+      - update
+  - name: me_phone
+    controller: CommandTower::Me::PhoneController
+    only:
+      - update
+      - destroy
+  - name: me_phone_verification_send
+    controller: CommandTower::Me::PhoneVerification::VerificationsController
+    only: create
+  - name: me_phone_verification_verify
+    controller: CommandTower::Me::PhoneVerification::VerifyController
+    only: create
+  - name: me_pushover
+    controller: CommandTower::Me::PushoverController
+    only:
+      - show
+      - create
+      - update
+      - destroy
+  - name: me_pushover_verification
+    controller: CommandTower::Me::Pushover::VerificationsController
+    only: create
+  - name: me_audit_events
+    controller: CommandTower::Me::AuditEventsController
+    only:
+      - index
+      - show
+      - filter_options
+  - name: admin_messaging_announcements
+    controller: CommandTower::Admin::Messaging::AnnouncementsController
+    only: create
+  - name: admin_audit_events
+    controller: CommandTower::Admin::Audit::EventsController
+    only:
+      - index
+      - show
+      - filter_options
+  - name: admin_workspace
+    controller: CommandTower::Admin::WorkspaceController
+    only: show
+  - name: admin_users
+    controller: CommandTower::Admin::UsersController
+    only:
+      - index
+      - show
+  - name: admin_users_update
+    controller: CommandTower::Admin::Users::IdentitiesController
+    only:
+      - update_name
+      - update_username
+      - update_email
+      - update_email_validation
+  - name: admin_rbac_assignments
+    controller: CommandTower::Admin::Users::RolesController
+    only:
+      - index
+      - update
+  - name: admin_impersonation
+    controller: CommandTower::Admin::Users::ImpersonationSessionsController
+    only: create
+  - name: principal_capabilities
+    controller: CommandTower::Auth::PrincipalCapabilitiesController
     only: show
-  - name: admin
-    controller: CommandTower::AdminController
-  - name: admin-without-impersonate
-    controller: CommandTower::AdminController
-    except: impersonate
-
-
-

data/lib/command_tower/authorization/effective_entity_grants.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Authorization
+    # Composed RBAC graph → effective entity name sets.
+    # Backend policy only. Not a frontend authorization shortcut.
+    module EffectiveEntityGrants
+      ALL = :all
+
+      module_function
+
+      def allow_everything?(user)
+        Array(user.roles).any? do |role_name|
+          role = CommandTower::Authorization::Role.roles[role_name]
+          role&.allow_everything
+        end
+      end
+
+      def for_user(user)
+        return ALL if allow_everything?(user)
+
+        for_role_names(Array(user.roles))
+      end
+
+      def for_role_names(role_names)
+        names = Array(role_names).map(&:to_s)
+        if names.any? { |name| CommandTower::Authorization::Role.roles[name]&.allow_everything }
+          return ALL
+        end
+
+        names.each_with_object(Set.new) do |name, grants|
+          role = CommandTower::Authorization::Role.roles[name]
+          next unless role
+
+          role.entities.each { |entity| grants << entity.name.to_s }
+        end
+      end
+
+      def for_role(role_name)
+        for_role_names([role_name])
+      end
+
+      def includes?(grants, entity_name)
+        grants == ALL || grants.include?(entity_name.to_s)
+      end
+
+      def subset?(candidate_grants, actor_grants)
+        return true if actor_grants == ALL
+        return false if candidate_grants == ALL
+
+        candidate_grants.subset?(actor_grants)
+      end
+    end
+  end
+end

data/lib/command_tower/authorization/entity.rb

@@ -4,13 +4,21 @@ module CommandTower
   module Authorization
     class Entity
       class << self
-        def create_entity(name:, controller:, only: nil, except: nil)
+        def create_entity(name:, controller:, only: nil, except: nil, source: :host)
           if entities[name]
-            Rails.logger.warn("Warning: Authorization entity #{name} duplicated. Only the most recent one will persist")
+            raise Error, "Authorization entity [#{name}] already exists. Hosts must not redefine CommandTower-owned entities."
           end
 
-          entities[name] = new(name:, controller:, only:, except:)
+          entity = new(name:, controller:, only:, except:, source:)
 
+          if source.to_sym == :host
+            ct_controllers = entities.values.select { |existing| existing.source == :command_tower }.map(&:controller)
+            if ct_controllers.include?(entity.controller)
+              raise Error, "Host entity [#{name}] redefines CommandTower-owned controller [#{entity.controller}]"
+            end
+          end
+
+          entities[name] = entity
           entities[name]
         end
 
@@ -23,11 +31,13 @@ module CommandTower
         end
       end
 
-      attr_reader :name, :controller, :only, :except
-      def initialize(name:, controller:, only: nil, except: nil)
+      attr_reader :name, :controller, :only, :except, :source
+      def initialize(name:, controller:, only: nil, except: nil, source: :host)
         @controller = controller
         @except = except.nil? ? nil : Array(except).map(&:to_sym)
         @only = only.nil? ? nil : Array(only).map(&:to_sym)
+        @source = source.to_sym
+        @name = name
 
         validate!
       end

data/lib/command_tower/authorization/role.rb

@@ -4,7 +4,7 @@ module CommandTower
   module Authorization
     class Role
       class << self
-        def create_role(name:, description:, entities: nil, allow_everything: false)
+        def create_role(name:, description:, entities: nil, allow_everything: false, source: :host)
           if roles[name]
             raise Error, "Role [#{name}] already exists. Must use different name"
           end
@@ -17,7 +17,7 @@ module CommandTower
             end
           end
 
-          roles[name] = new(name:, description:, entities:, allow_everything:)
+          roles[name] = new(name:, description:, entities:, allow_everything:, source:)
           # A role is `intended` to be immutable (attr_reader)
           # Once the role is defined it will not get changed
           # After it is created, add the mapping to the source of truth list of mapped method names to their controllers
@@ -35,12 +35,13 @@ module CommandTower
         end
       end
 
-      attr_reader :entities, :name, :description, :allow_everything
-      def initialize(name:, description:, entities:, allow_everything: false)
+      attr_reader :entities, :name, :description, :allow_everything, :source
+      def initialize(name:, description:, entities:, allow_everything: false, source: :host)
         @name = name
         @entities = Array(entities)
         @description = description
         @allow_everything = allow_everything
+        @source = source.to_sym
       end
 
       def authorized?(controller:, method:, user:)

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/application/config.rb

@@ -21,12 +21,12 @@ module CommandTower
 
         add_composer :url,
           allowed: String,
-          default: ENV.fetch("command_tower_URL", "http://localhost"),
+          default: ENV.fetch("COMMAND_TOWER_FRONTEND_URL", "http://localhost"),
           desc: "When composing SSO's or verification URL's, this is the URL for the application"
 
         add_composer :port,
           allowed: [String, NilClass],
-          default: ENV.fetch("command_tower_PORT", nil),
+          default: ENV.fetch("COMMAND_TOWER_FRONTEND_PORT", nil),
           desc: "When composing SSO's or verification URL's, this is the PORT for the application"
 
         add_composer :composed_url,

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/base.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "class_composer"
-require "pry"
 
 module CommandTower
   module Configuration

data/lib/command_tower/configuration/config.rb

@@ -3,14 +3,23 @@
 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"
+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"
 
@@ -39,6 +48,11 @@ module CommandTower
         allowed: Configuration::Email::Config,
         default: Configuration::Email::Config.new
 
+      add_composer :credentials,
+        desc: "Deployment provider credentials (typed per provider under config.credentials.<provider>). Consumed by Credential Resolution. Not provider behavior configuration.",
+        allowed: Configuration::Credentials::Config,
+        default: Configuration::Credentials::Config.new
+
       add_composer :username,
         desc: "Username configuration for the app",
         allowed: Configuration::Username::Config,
@@ -62,16 +76,53 @@ module CommandTower
         allowed: Configuration::User::Config,
         default: Configuration::User::Config.new
 
+      add_composer :identity,
+        desc: "Identity-owned capabilities (phone verification OTP, etc.)",
+        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,
+        default: Configuration::Messaging::Config.new
+
       add_composer :admin,
         desc: "Admin configuration for the app",
         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,
+        default: Configuration::SignupSession::Config.new
+
+      add_composer :password_recovery_session,
+        desc: "Password recovery session token claims, TTL, and recovery rate limit ceilings",
+        allowed: Configuration::PasswordRecoverySession::Config,
+        default: Configuration::PasswordRecoverySession::Config.new
+
       # To be Deleted
       add_composer :otp,
         desc: "One Time Password generation is used for ease in quickly validating a users actions. This is good for short term validation requirements as opposed to UserSecrets",
@@ -80,4 +131,3 @@ module CommandTower
     end
   end
 end
-