command_tower 0.3.1 → 0.10.0

data/lib/command_tower/configuration/messaging/sms.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Messaging
+      class Sms < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        ADAPTERS = %w[disabled fake twilio log].freeze
+
+        add_composer :adapter,
+          desc: "Messaging notification SMS adapter: disabled | fake | twilio | log. Default disabled (fail closed).",
+          allowed: String,
+          default: "disabled",
+          validator: ->(val) { ADAPTERS.include?(val.to_s) },
+          invalid_message: ->(val) { "Provided #{val.inspect}. Allowed: #{ADAPTERS.join(', ')}" }
+
+        add_composer :from_number,
+          desc: "Sender phone number for Twilio notification SMS (E.164). Falls back to ENV TWILIO_FROM when blank.",
+          allowed: [String, NilClass],
+          default: nil
+
+        add_composer :messaging_service_sid,
+          desc: "Twilio Messaging Service SID for notification SMS. Preferred over from_number when both are set.",
+          allowed: [String, NilClass],
+          default: nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Configuration
+    module Pagination
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :limit,
+          desc: "Default Limit for pagination return when not present on service or query/body. Negative values are treated like no limit",
+          allowed: Integer,
+          default: 10
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "class_composer"
+require "command_tower/configuration/password_recovery_session/rate_limits"
+
+module CommandTower
+  module Configuration
+    module PasswordRecoverySession
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        # Claim defaults are wire contract: changing them invalidates tokens already
+        # issued to password recovery clients.
+        add_composer :issuer,
+          desc: "`iss` claim stamped on password recovery session tokens",
+          allowed: String,
+          default: "command_tower:password-recovery"
+
+        add_composer :audience,
+          desc: "`aud` claim stamped on password recovery session tokens",
+          allowed: String,
+          default: "password-recovery-send"
+
+        add_composer :purpose,
+          desc: "`purpose` claim stamped on password recovery session tokens",
+          allowed: String,
+          default: "password-recovery"
+
+        add_composer :ttl,
+          desc: "How long an issued password recovery session token remains valid",
+          allowed: ActiveSupport::Duration,
+          default: 15.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 PASSWORD_RECOVERY_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 password recovery session tokens. Host must set this outside of test",
+          allowed: String,
+          default: (
+            ENV["PASSWORD_RECOVERY_SESSION_JWT_SECRET"].presence ||
+              (defined?(Rails) && Rails.env.test? ? "test-password-recovery-session-jwt-secret" : "")
+          )
+
+        add_composer :rate_limits,
+          desc: "Password recovery rate limit ceilings applied per recovery 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/password_recovery_session/rate_limits.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module PasswordRecoverySession
+      class RateLimits < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :jti_send,
+          desc: "Max password reset sends allowed for a single recovery session (jti)",
+          allowed: Integer,
+          default: 5
+
+        add_composer :ip_issue_burst,
+          desc: "Max recovery session tokens a single IP may request per minute",
+          allowed: Integer,
+          default: 5
+
+        add_composer :ip_issue_hour,
+          desc: "Max recovery session tokens a single IP may request per hour",
+          allowed: Integer,
+          default: 20
+
+        add_composer :ip_send_hour,
+          desc: "Max password reset sends a single IP may make per hour",
+          allowed: Integer,
+          default: 10
+      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,7 @@
+# frozen_string_literal: true
+
+module CommandTower
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :request_id
+  end
+end

data/lib/command_tower/engine.rb

@@ -10,13 +10,16 @@ module CommandTower
     # 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?
           # Now that we can confirm all variables are defined, freeze all objects an their children

data/lib/command_tower/install/baseline.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Install
+    # Compact final-schema baseline authored in CommandTower (Phase 5.2).
+    # Hosts receive copies via Rails-native `command_tower:install:migrations`.
+    module Baseline
+      ENGINE_MIGRATION_BASENAMES = %w[
+        20260805000001_create_command_tower_users.rb
+        20260805000002_create_command_tower_user_secrets.rb
+        20260805000003_create_command_tower_messaging_core.rb
+        20260805000004_create_messaging_notification_preferences.rb
+        20260805000005_create_messaging_endpoints_and_pushover_credentials.rb
+      ].freeze
+
+      module_function
+
+      def migrate_dir
+        CommandTower::Engine.root.join("db/migrate")
+      end
+
+      def engine_migration_basenames
+        Dir.children(migrate_dir).grep(/\.rb\z/).sort
+      end
+
+      def host_installed_migrations(host_root = Rails.root)
+        Dir.glob(File.join(host_root.to_s, "db/migrate", "*command_tower*.rb")).map { |p| File.basename(p) }.sort
+      end
+    end
+  end
+end