command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "class_composer"
+require "command_tower/configuration/signup_session/email_availability"
+require "command_tower/configuration/signup_session/rate_limits"
+
+module CommandTower
+  module Configuration
+    module SignupSession
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer_blocking :email_availability,
+          desc: "Route gate for modern email availability HTTP (GET /auth/email/availability)",
+          composer_class: EmailAvailability,
+          enable_attr: :enable
+
+        # Claim defaults are wire contract: changing them invalidates tokens already
+        # issued to signup clients.
+        add_composer :issuer,
+          desc: "`iss` claim stamped on signup session tokens",
+          allowed: String,
+          default: "command_tower:signup"
+
+        add_composer :audience,
+          desc: "`aud` claim stamped on signup session tokens",
+          allowed: String,
+          default: "signup-availability"
+
+        add_composer :purpose,
+          desc: "`purpose` claim stamped on signup session tokens",
+          allowed: String,
+          default: "signup"
+
+        add_composer :ttl,
+          desc: "How long an issued signup session token remains valid",
+          allowed: ActiveSupport::Duration,
+          default: 20.minutes
+
+        add_composer :cleanup_buffer_seconds,
+          desc: "Extra seconds added to per-session rate limit key TTLs so counters outlive the token",
+          allowed: Integer,
+          default: 300
+
+        # Host applications must supply this (config or SIGNUP_SESSION_JWT_SECRET).
+        # Defaulting to "" rather than raising keeps gem load side-effect free; use
+        # `configured?` to fail closed at the point of use.
+        add_composer :jwt_secret,
+          desc: "HS256 secret used to sign signup session tokens. Host must set this outside of test",
+          allowed: String,
+          default: (
+            ENV["SIGNUP_SESSION_JWT_SECRET"].presence ||
+              (defined?(Rails) && Rails.env.test? ? "test-signup-session-jwt-secret" : "")
+          )
+
+        add_composer :rate_limits,
+          desc: "Signup rate limit ceilings applied per signup session and per client IP",
+          allowed: RateLimits,
+          default: RateLimits.new
+
+        def configured?
+          jwt_secret.present?
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/signup_session/email_availability.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module SignupSession
+      class EmailAvailability < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :enable,
+          desc: "Expose GET /auth/email/availability on Engine.routes when enabled",
+          allowed: [FalseClass, TrueClass],
+          default: true
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/signup_session/rate_limits.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module SignupSession
+      class RateLimits < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :jti_email,
+          desc: "Max email availability lookups allowed for a single signup session (jti)",
+          allowed: Integer,
+          default: 50
+
+        add_composer :jti_username,
+          desc: "Max username availability lookups allowed for a single signup session (jti)",
+          allowed: Integer,
+          default: 50
+
+        add_composer :jti_total,
+          desc: "Max combined availability lookups allowed for a single signup session (jti)",
+          allowed: Integer,
+          default: 80
+
+        add_composer :ip_issue_burst,
+          desc: "Max signup session tokens a single IP may request per minute",
+          allowed: Integer,
+          default: 15
+
+        add_composer :ip_issue_hour,
+          desc: "Max signup session tokens a single IP may request per hour",
+          allowed: Integer,
+          default: 60
+
+        add_composer :ip_availability_hour,
+          desc: "Max availability lookups a single IP may make per hour",
+          allowed: Integer,
+          default: 200
+
+        add_composer :ip_register_hour,
+          desc: "Max registration attempts a single IP may make per hour",
+          allowed: Integer,
+          default: 20
+      end
+    end
+  end
+end

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

@@ -12,24 +12,25 @@ module CommandTower
           :email,
           :first_name,
           :last_name,
-          :last_known_timezone,
           :username,
           :verifier_token,
         ]
 
         ATTRIBUTES_TO_SHOW = [
-          *ATTRIBUTES_TO_CHANGE,
+          *(ATTRIBUTES_TO_CHANGE - [:verifier_token]),
+          :created_at,
+          :email_validated,
           :id,
+          :last_known_timezone,
           :roles,
-          :created_at,
         ]
 
         ATTRIBUTES_CHANGE_EXECUTE = Proc.new do |key, value|
-          CommandTower::UserAttributes::Modify.assign!
+          CommandTower::UserAttributes::Mutate.assign!
         end
 
         ATTRIBUTES_SHOWN_EXECUTE = Proc.new do |key, value|
-          CommandTower::Schema::User.assign!
+          CommandTower::Schema::Shared::User.assign!
         end
 
         add_composer :additional_attributes_for_change,

data/lib/command_tower/credential_resolution/env_backend.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module CredentialResolution
+    # Default ENV-backed credential source (precedence tier 3).
+    # Documented keys only — provider consumers must not call this directly.
+    module EnvBackend
+      module_function
+
+      def twilio
+        TwilioCredentials.new(
+          account_sid: ENV["TWILIO_ACCOUNT_SID"],
+          auth_token: ENV["TWILIO_AUTH_TOKEN"],
+        )
+      end
+
+      def smtp
+        SmtpCredentials.new(
+          user_name: ENV["GMAIL_USER_NAME"],
+          password: ENV["GMAIL_PASSWORD"],
+        )
+      end
+    end
+  end
+end

data/lib/command_tower/credential_resolution/smtp_action_mailer_bridge.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module CredentialResolution
+    # Applies resolved SMTP credentials into ActionMailer smtp_settings.
+    # Delivery contract remains ActionMailer; Credential Resolution only supplies secrets.
+    module SmtpActionMailerBridge
+      module_function
+
+      def apply!
+        return unless defined?(Rails) && Rails.respond_to?(:configuration)
+
+        credentials = CredentialResolution.resolve(:smtp)
+        return unless credentials.available?
+
+        hash = Rails.configuration.action_mailer.smtp_settings ||= {}
+        Rails.configuration.action_mailer.smtp_settings = hash.merge(
+          user_name: credentials.user_name,
+          password: credentials.password,
+        )
+      end
+    end
+  end
+end

data/lib/command_tower/credential_resolution/smtp_credentials.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module CredentialResolution
+    # Typed SMTP deployment credentials. Never log or serialize raw values.
+    class SmtpCredentials
+      attr_reader :user_name, :password
+
+      def initialize(user_name:, password:)
+        @user_name = user_name.to_s.strip
+        @password = password.to_s.strip
+        freeze
+      end
+
+      def available?
+        user_name.present? && password.present?
+      end
+
+      def inspect
+        "#<#{self.class.name} user_name=[REDACTED] password=[REDACTED] available?=#{available?}>"
+      end
+
+      alias_method :pretty_inspect, :inspect
+    end
+  end
+end

data/lib/command_tower/credential_resolution/twilio_credentials.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module CredentialResolution
+    # Typed Twilio deployment credentials. Never log or serialize raw values.
+    class TwilioCredentials
+      attr_reader :account_sid, :auth_token
+
+      def initialize(account_sid:, auth_token:)
+        @account_sid = account_sid.to_s.strip
+        @auth_token = auth_token.to_s.strip
+        freeze
+      end
+
+      def available?
+        account_sid.present? && auth_token.present?
+      end
+
+      def inspect
+        "#<#{self.class.name} account_sid=[REDACTED] auth_token=[REDACTED] available?=#{available?}>"
+      end
+
+      alias_method :pretty_inspect, :inspect
+    end
+  end
+end

data/lib/command_tower/credential_resolution.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "command_tower/credential_resolution/twilio_credentials"
+require "command_tower/credential_resolution/smtp_credentials"
+require "command_tower/credential_resolution/env_backend"
+require "command_tower/credential_resolution/smtp_action_mailer_bridge"
+
+module CommandTower
+  # Provider-facing deployment credential normalization.
+  # Hosts supply via config.credentials.*, custom resolver, and/or ENV.
+  # Providers call resolve only — never branch on source.
+  module CredentialResolution
+    PROVIDERS = {
+      twilio: TwilioCredentials,
+      smtp: SmtpCredentials,
+    }.freeze
+
+    module_function
+
+    def resolve(provider)
+      key = normalize_provider!(provider)
+
+      explicit = explicit_credentials(key)
+      return explicit if explicit.available?
+
+      custom = custom_resolver_credentials(key)
+      return custom if custom&.available?
+
+      env_credentials(key)
+    end
+
+    def normalize_provider!(provider)
+      key = provider.to_sym
+      raise ArgumentError, "Unknown credential provider: #{provider.inspect}" unless PROVIDERS.key?(key)
+
+      key
+    end
+    private_class_method :normalize_provider!
+
+    def explicit_credentials(key)
+      case key
+      when :twilio
+        cfg = CommandTower.config.credentials.twilio
+        TwilioCredentials.new(account_sid: cfg.account_sid, auth_token: cfg.auth_token)
+      when :smtp
+        cfg = CommandTower.config.credentials.smtp
+        SmtpCredentials.new(user_name: cfg.user_name, password: cfg.password)
+      end
+    end
+    private_class_method :explicit_credentials
+
+    def custom_resolver_credentials(key)
+      resolver = CommandTower.credential_resolver
+      return nil if resolver.nil?
+
+      unless resolver.respond_to?(:resolve)
+        raise ArgumentError, "credential_resolver must respond to #resolve(provider)"
+      end
+
+      result = resolver.resolve(key)
+      expected = PROVIDERS.fetch(key)
+      unless result.is_a?(expected)
+        raise TypeError, "credential_resolver for #{key.inspect} must return #{expected.name}"
+      end
+
+      result
+    end
+    private_class_method :custom_resolver_credentials
+
+    def env_credentials(key)
+      case key
+      when :twilio then EnvBackend.twilio
+      when :smtp then EnvBackend.smtp
+      end
+    end
+    private_class_method :env_credentials
+  end
+end

data/lib/command_tower/current.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+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,18 +7,28 @@ 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
-      db_rake_task = defined?(Rake) && (Rake.application.top_level_tasks.any? { |task| task =~ /db:/ } rescue nil)
+      db_rake_task = defined?(Rake) && (Rake.application.top_level_tasks.any? { |task|
+        task =~ /db:|install:migrations|command_tower:install\z|command_tower:doctor/
+      } rescue nil)
       if db_rake_task
         # Because we call the Database during configuration setup,
         # We want to skip calling the DB during a DB migration
       else
         # ensure defaults are instantiated and all variables are assigned
         CommandTower.config.class_composer_assign_defaults!(children: true)
+        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
@@ -43,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