command_tower 0.4.0 → 0.11.0

data/lib/command_tower/install/doctor.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "command_tower/install/baseline"
+require "command_tower/configuration/messaging/sms"
+require "command_tower/configuration/messaging/pushover"
+
+module CommandTower
+  module Install
+    # Friendly setup validation for host applications.
+    # Returns structured findings; rake task prints remediation text.
+    class Doctor
+      INSECURE_JWT_DEFAULT = "Thi$IsASeccretIwi::CH&ang3"
+      SUPPORTED_SMS_ADAPTERS = Configuration::Messaging::Sms::ADAPTERS
+      SUPPORTED_PUSHOVER_ADAPTERS = Configuration::Messaging::Pushover::ADAPTERS
+      Finding = Struct.new(:severity, :code, :message, :remediation, keyword_init: true)
+
+      def initialize(host_root: Rails.root, config: CommandTower.config, env: Rails.env)
+        @host_root = Pathname(host_root)
+        @config = config
+        @env = env.to_s
+      end
+
+      def run
+        findings = []
+        findings.concat(check_rails_version)
+        findings.concat(check_engine_migrations)
+        findings.concat(check_host_migrations)
+        findings.concat(check_jwt_secret)
+        findings.concat(check_session_secrets)
+        findings.concat(check_messaging_adapters)
+        findings
+      end
+
+      def ok?
+        run.none? { |f| f.severity == :fail }
+      end
+
+      private
+
+      attr_reader :host_root, :config, :env
+
+      def check_rails_version
+        version = Gem::Version.new(Rails::VERSION::STRING)
+        min = Gem::Version.new("7.0.0")
+        max = Gem::Version.new("9.0.0")
+        if version >= min && version < max
+          [Finding.new(
+            severity: :pass,
+            code: :rails_version,
+            message: "Rails #{Rails::VERSION::STRING} is supported",
+            remediation: nil
+          )]
+        else
+          [Finding.new(
+            severity: :fail,
+            code: :rails_version,
+            message: "Rails #{Rails::VERSION::STRING} is outside CommandTower's supported range",
+            remediation: "Use Rails >= 7.0 and < 9.0 (see command_tower.gemspec)."
+          )]
+        end
+      end
+
+      def check_engine_migrations
+        actual = Baseline.engine_migration_basenames
+        expected = Baseline::ENGINE_MIGRATION_BASENAMES
+        if actual == expected
+          [Finding.new(
+            severity: :pass,
+            code: :engine_migrations,
+            message: "Engine ships the #{expected.size}-migration baseline",
+            remediation: nil
+          )]
+        else
+          [Finding.new(
+            severity: :fail,
+            code: :engine_migrations,
+            message: "Engine migration inventory does not match the expected baseline",
+            remediation: "Expected #{expected.join(', ')}; found #{actual.join(', ') || '(none)'}."
+          )]
+        end
+      end
+
+      def check_host_migrations
+        installed = Baseline.host_installed_migrations(host_root)
+        expected_count = Baseline::ENGINE_MIGRATION_BASENAMES.size
+
+        if installed.empty?
+          [Finding.new(
+            severity: :fail,
+            code: :host_migrations,
+            message: "No CommandTower migrations installed in the host",
+            remediation: "Run `bin/rails command_tower:install` (or `command_tower:install:migrations`), then `bin/rails db:migrate`."
+          )]
+        elsif installed.size < expected_count
+          [Finding.new(
+            severity: :fail,
+            code: :host_migrations,
+            message: "Host has #{installed.size} CommandTower migration(s); expected at least #{expected_count}",
+            remediation: "Run `bin/rails command_tower:install:migrations` after upgrading the gem, then `bin/rails db:migrate`."
+          )]
+        else
+          [Finding.new(
+            severity: :pass,
+            code: :host_migrations,
+            message: "Host has #{installed.size} installed CommandTower migration(s)",
+            remediation: nil
+          )]
+        end
+      end
+
+      def check_jwt_secret
+        secret = config.jwt.hmac_secret.to_s
+        if secret.blank?
+          return [Finding.new(
+            severity: :fail,
+            code: :jwt_secret,
+            message: "JWT HMAC secret is blank",
+            remediation: "Set `config.jwt.hmac_secret` (typically `ENV.fetch(\"SECRET_KEY_BASE\") { Rails.application.secret_key_base }`)."
+          )]
+        end
+
+        if secret == INSECURE_JWT_DEFAULT
+          severity = production? ? :fail : :warn
+          return [Finding.new(
+            severity: severity,
+            code: :jwt_secret,
+            message: "JWT HMAC secret is still the insecure CommandTower default",
+            remediation: "Set `config.jwt.hmac_secret` from SECRET_KEY_BASE or Rails.application.secret_key_base before deploying."
+          )]
+        end
+
+        [Finding.new(
+          severity: :pass,
+          code: :jwt_secret,
+          message: "JWT HMAC secret is configured",
+          remediation: nil
+        )]
+      end
+
+      def check_session_secrets
+        findings = []
+
+        unless production_or_development_missing_ok?(config.signup_session.jwt_secret)
+          findings << Finding.new(
+            severity: production? ? :warn : :warn,
+            code: :signup_session_secret,
+            message: "Signup session JWT secret is blank",
+            remediation: "Set `config.signup_session.jwt_secret` or ENV SIGNUP_SESSION_JWT_SECRET."
+          )
+        else
+          findings << Finding.new(
+            severity: :pass,
+            code: :signup_session_secret,
+            message: "Signup session JWT secret is configured",
+            remediation: nil
+          )
+        end
+
+        unless production_or_development_missing_ok?(config.password_recovery_session.jwt_secret)
+          findings << Finding.new(
+            severity: :warn,
+            code: :password_recovery_secret,
+            message: "Password recovery session JWT secret is blank",
+            remediation: "Set `config.password_recovery_session.jwt_secret` or ENV PASSWORD_RECOVERY_SESSION_JWT_SECRET."
+          )
+        else
+          findings << Finding.new(
+            severity: :pass,
+            code: :password_recovery_secret,
+            message: "Password recovery session JWT secret is configured",
+            remediation: nil
+          )
+        end
+
+        findings
+      end
+
+      def check_messaging_adapters
+        findings = []
+        sms = config.messaging.sms.adapter.to_s
+        pushover = config.messaging.pushover.adapter.to_s
+
+        if sms.present? && !SUPPORTED_SMS_ADAPTERS.include?(sms)
+          findings << Finding.new(
+            severity: :warn,
+            code: :sms_adapter,
+            message: "Unsupported messaging SMS adapter #{sms.inspect}",
+            remediation: "Use one of: #{SUPPORTED_SMS_ADAPTERS.join(', ')}."
+          )
+        else
+          findings << Finding.new(
+            severity: :pass,
+            code: :sms_adapter,
+            message: "Messaging SMS adapter is #{sms.presence || 'blank (defaults apply)'}",
+            remediation: nil
+          )
+        end
+
+        if pushover.present? && !SUPPORTED_PUSHOVER_ADAPTERS.include?(pushover)
+          findings << Finding.new(
+            severity: :warn,
+            code: :pushover_adapter,
+            message: "Unsupported messaging Pushover adapter #{pushover.inspect}",
+            remediation: "Use one of: #{SUPPORTED_PUSHOVER_ADAPTERS.join(', ')}."
+          )
+        else
+          findings << Finding.new(
+            severity: :pass,
+            code: :pushover_adapter,
+            message: "Messaging Pushover adapter is #{pushover.presence || 'blank (defaults apply)'}",
+            remediation: nil
+          )
+        end
+
+        findings
+      end
+
+      def production_or_development_missing_ok?(secret)
+        secret.to_s.present? || env == "test"
+      end
+
+      def production?
+        env == "production"
+      end
+    end
+  end
+end

data/lib/command_tower/jwt/authorization_helper.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Jwt
+    module AuthorizationHelper
+      AUTHENTICATION_HEADER = "Authorization"
+      AUTHENTICATION_EXPIRE_HEADER = "X-Authorization-Expire"
+      AUTHENTICATION_WITH_RESET = "X-Authorization-Reset"
+
+      module_function
+
+      # Validates and extracts token from Authorization header OR cookie (if enabled)
+      # Returns hash with :token and :source on success, or hash with :error and :message on failure
+      # @param request [ActionDispatch::Request] The request object
+      # @return [Hash] Hash with :token and :source (:header, :cookie) on success, or :error and :message on failure
+      def extract_token(request)
+        # First try Authorization header
+        raw_token = request.headers[AUTHENTICATION_HEADER]
+        if raw_token && !raw_token.to_s.strip.empty?
+          # Validate Bearer format with strict regex (case-insensitive)
+          # Matches: \ABearer\s+(.+)\z
+          # - \A: start of string
+          # - Bearer: literal "Bearer" (case-insensitive with /i flag)
+          # - \s+: one or more whitespace characters
+          # - (.+): capture group for token (one or more characters)
+          # - \z: end of string
+          match = raw_token.match(/\ABearer\s+(.+)\z/i)
+          if match && match[1] && !match[1].strip.empty?
+            token = match[1].strip
+            return { token:, source: :header }
+          else
+            return { error: :invalid_format, message: "Invalid Bearer token format" }
+          end
+        end
+
+        # Fallback to cookie if header is missing/empty AND cookie enabled
+        if cookie_enabled?
+          cookie_token = read_cookie(request)
+          return { token: cookie_token, source: :cookie } if cookie_token && !cookie_token.strip.empty?
+        end
+
+        # No token found
+        { error: :missing, message: "Bearer token missing" }
+      end
+
+      # Sets token in response (headers and optionally cookie)
+      # @param response [ActionDispatch::Response] The response object
+      # @param token [String] The JWT token to set
+      # @param expires_at [String, nil] Optional expiration time string
+      def set_token(response, token, expires_at: nil)
+        # Always set headers
+        response.set_header(AUTHENTICATION_WITH_RESET, token)
+        response.set_header(AUTHENTICATION_EXPIRE_HEADER, expires_at) if expires_at && !expires_at.to_s.strip.empty?
+
+        # Set cookie if enabled
+        set_cookie(response, token) if cookie_enabled?
+      end
+
+      # Clears token from response (cookie only, headers are response-only)
+      # @param response [ActionDispatch::Response] The response object
+      def clear_token(response)
+        clear_cookie(response) if cookie_enabled?
+        # Clear CSRF cookie on logout
+        # Logout always clears CSRF cookie (not configurable - this is the only correct behavior)
+        CommandTower::Jwt::CsrfHelper.clear_cookie(response) if CommandTower::Jwt::CsrfHelper.csrf_enabled?
+      end
+
+      # Reads cookie value from request
+      # @param request [ActionDispatch::Request] The request object
+      # @return [String, nil] Cookie value or nil
+      def read_cookie(request)
+        return nil unless cookie_enabled?
+
+        request.cookies[CommandTower.config.jwt.cookie.name.downcase]
+      end
+
+      # Returns consistent cookie options hash (single source of truth)
+      # @param expires_at [Time, ActiveSupport::TimeWithZone] Expiration time for the cookie
+      # @return [Hash] Cookie options hash with all attributes
+      def cookie_options(expires_at:)
+        config = CommandTower.config.jwt.cookie
+        secure_value = config.secure || Rails.env.production?
+        options = {
+          expires: expires_at,
+          httponly: config.httponly,
+          secure: secure_value,
+          same_site: config.same_site,
+          path: config.path
+        }
+        options[:domain] = config.domain if config.domain.present?
+        options
+      end
+
+      # Sets cookie with configured options
+      # @param response [ActionDispatch::Response] The response object
+      # @param token [String] The JWT token to set
+      def set_cookie(response, token)
+        return unless cookie_enabled?
+
+        config = CommandTower.config.jwt.cookie
+        options = cookie_options(expires_at: config.ttl.from_now)
+        options[:value] = token
+
+        response.set_cookie(config.name, options)
+      end
+
+      # Clears cookie by setting it to expire in the past
+      # @param response [ActionDispatch::Response] The response object
+      def clear_cookie(response)
+        return unless cookie_enabled?
+
+        config = CommandTower.config.jwt.cookie
+        options = cookie_options(expires_at: 1.year.ago)
+        options[:value] = ""
+
+        response.set_cookie(config.name, options)
+      end
+
+      # Gets the with_reset flag from request headers
+      # @param request [ActionDispatch::Request] The request object
+      # @return [Boolean, nil] The boolean value or nil
+      def get_with_reset_flag(request)
+        value = request.headers[AUTHENTICATION_WITH_RESET]
+        return nil unless [true, false, "true", "false", "0", "1", 0, 1].include?(value)
+
+        ActiveModel::Type::Boolean.new.cast(value)
+      end
+
+      # Checks if cookie auth is enabled
+      # @return [Boolean]
+      def cookie_enabled?
+        CommandTower.config.jwt.cookie.enabled?
+      end
+    end
+  end
+end

data/lib/command_tower/jwt/csrf_helper.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "active_support/security_utils"
+
+module CommandTower
+  module Jwt
+    module CsrfHelper
+      module_function
+
+      # Generate a new CSRF token
+      def generate_token
+        SecureRandom.hex(32)
+      end
+
+      # Set CSRF cookie in response
+      def set_cookie(response, token)
+        return unless csrf_enabled?
+
+        config = CommandTower.config.jwt.cookie.csrf
+        options = csrf_cookie_options(expires_at: config.ttl.from_now)
+        options[:value] = token
+
+        response.set_cookie(config.cookie_name, options)
+      end
+
+      # Clear CSRF cookie
+      def clear_cookie(response)
+        return unless csrf_enabled?
+
+        config = CommandTower.config.jwt.cookie.csrf
+        options = csrf_cookie_options(expires_at: 1.year.ago)
+        options[:value] = ""
+        options[:max_age] = 0
+
+        response.set_cookie(config.cookie_name, options)
+      end
+
+      # Ensure CSRF cookie exists (rotate-or-ensure model)
+      # - If should_rotate is true → generate + set new CSRF cookie
+      # - Else if existing cookie is blank → generate + set new CSRF cookie
+      # - Else do nothing (cookie already exists)
+      def ensure_cookie(request, response, should_rotate: false)
+        return unless csrf_enabled?
+
+        # Read cookie once into local variable
+        existing_cookie = read_cookie(request)
+        existing_cookie_blank = existing_cookie.nil? || existing_cookie.strip.empty?
+
+        if should_rotate || existing_cookie_blank
+          # Generate and set new CSRF cookie
+          token = generate_token
+          set_cookie(response, token)
+        end
+        # Else: cookie exists and we're not rotating, do nothing
+      end
+
+      # Read CSRF token from cookie
+      def read_cookie(request)
+        return nil unless csrf_enabled?
+
+        config = CommandTower.config.jwt.cookie.csrf
+        request.cookies[config.cookie_name]
+      end
+
+      # Read CSRF token from header
+      def read_header(request)
+        return nil unless csrf_enabled?
+
+        config = CommandTower.config.jwt.cookie.csrf
+        request.headers[config.header_name]
+      end
+
+      # Validate CSRF token (compare cookie to header)
+      # Uses constant-time comparison for security hardening
+      def validate(request)
+        return { valid: true } unless csrf_enabled?
+
+        # read_cookie and read_header also check csrf_enabled?, but that's fine for redundancy
+        cookie_token = read_cookie(request)
+        header_token = read_header(request)
+
+        if cookie_token.nil? || cookie_token.strip.empty?
+          return { valid: false, error: :csrf_missing, message: "csrf_missing" }
+        end
+
+        if header_token.nil? || header_token.strip.empty?
+          return { valid: false, error: :csrf_mismatch, message: "csrf_missing" }
+        end
+
+        # Normalize tokens
+        cookie_normalized = cookie_token.to_s.strip
+        header_normalized = header_token.to_s.strip
+
+        # Use constant-time comparison to prevent timing attacks
+        if cookie_normalized.length != header_normalized.length
+          return { valid: false, error: :csrf_mismatch, message: "csrf_mismatch" }
+        end
+
+        unless ActiveSupport::SecurityUtils.secure_compare(cookie_normalized, header_normalized)
+          return { valid: false, error: :csrf_mismatch, message: "csrf_mismatch" }
+        end
+
+        { valid: true }
+      end
+
+      # Check if CSRF is enabled
+      # CSRF can only be enabled when cookie auth is also enabled
+      def csrf_enabled?
+        CommandTower::Jwt::AuthorizationHelper.cookie_enabled? && CommandTower.config.jwt.cookie.csrf.enabled?
+      end
+
+      # Get cookie options (single source of truth)
+      # Uses explicit nil checks (not ||) for true nil-coalescing of inheritable fields
+      def csrf_cookie_options(expires_at:)
+        config = CommandTower.config.jwt.cookie.csrf
+        jwt_config = CommandTower.config.jwt.cookie
+
+        # Boolean handling for secure (already fixed)
+        secure_value = config.secure.nil? ? (jwt_config.secure.nil? ? Rails.env.production? : jwt_config.secure) : config.secure
+
+        # Explicit nil checks for same_site, path, domain (not || to respect explicit false/nil)
+        same_site_value = config.same_site.nil? ? jwt_config.same_site : config.same_site
+        path_value = config.path.nil? ? jwt_config.path : config.path
+        domain_value = config.domain.nil? ? jwt_config.domain : config.domain
+
+        options = {
+          expires: expires_at,
+          httponly: false,  # CRITICAL: Must be readable by JavaScript (defined once)
+          secure: secure_value,
+          same_site: same_site_value,
+          path: path_value
+        }
+        options[:domain] = domain_value if domain_value.present?
+        options
+      end
+    end
+  end
+end

data/lib/command_tower/logging/lifecycle_declaration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Logging
+    module LifecycleDeclaration
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def log_lifecycle!
+          @lifecycle_loggable = true
+        end
+
+        def disable_lifecycle_logging!
+          @lifecycle_loggable = false
+        end
+
+        def lifecycle_loggable?
+          return @lifecycle_loggable unless @lifecycle_loggable.nil?
+
+          superclass.respond_to?(:lifecycle_loggable?) ? superclass.lifecycle_loggable? : false
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/logging/projection.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Logging
+    module Projection
+      DROP = %i[event_uuid layer log_lifecycle log_level].freeze
+
+      module_function
+
+      def call(event)
+        payload = symbolize(event.payload)
+        projected = { event: event.name }
+
+        copy_if_present(projected, payload, :subject)
+        copy_if_present(projected, payload, :execution_uuid)
+        copy_if_present(projected, payload, :correlation_id)
+        copy_if_present(projected, payload, :outcome)
+        copy_if_present(projected, payload, :duration_ms)
+        copy_if_present(projected, payload, :user_id)
+        copy_if_present(projected, payload, :error_class)
+        copy_if_present(projected, payload, :error_codes)
+        copy_if_present(projected, payload, :causation_id)
+        copy_if_present(projected, payload, :originating_administrator_id)
+
+        request_id = payload[:request_id]
+        if !request_id.nil? && request_id != payload[:correlation_id]
+          projected[:request_id] = request_id
+        end
+
+        source = payload[:source]
+        projected[:source] = source if !source.nil? && source.to_s != "http"
+
+        effective = payload[:effective_user_id]
+        projected[:effective_user_id] = effective if !effective.nil? && effective != payload[:user_id]
+
+        projected[:impersonation_active] = true if payload[:impersonation_active] == true
+
+        payload.each do |key, value|
+          next if DROP.include?(key)
+          next if projected.key?(key)
+          next if value.nil?
+          next if key == :impersonation_active
+          next if key == :source
+          next if key == :request_id
+          next if key == :effective_user_id
+
+          projected[key] = value
+        end
+
+        projected
+      end
+
+      def symbolize(payload)
+        hash = payload.respond_to?(:to_h) ? payload.to_h : {}
+        hash.each_with_object({}) do |(key, value), memo|
+          memo[key.to_sym] = value
+        end
+      end
+
+      def copy_if_present(projected, payload, key)
+        value = payload[key]
+        projected[key] = value unless value.nil?
+      end
+      private_class_method :symbolize, :copy_if_present
+    end
+  end
+end

data/lib/command_tower/logging/subscriber.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Logging
+    class Subscriber < ActiveSupport::LogSubscriber
+      PATTERNS = [
+        /\Acommand_tower\.lifecycle(?:\.|\z)/,
+        /\Acommand_tower\.log(?:\.|\z)/,
+        /\Acommand_tower\.messaging(?:\.|\z)/
+      ].freeze
+      SEVERITIES = %i[debug info warn error].freeze
+
+      class << self
+        def logger
+          @logger || super
+        end
+
+        def logger=(value)
+          @logger = value
+        end
+
+        def attach!
+          detach!
+          subscriber = new
+          @subscriptions = PATTERNS.map do |pattern|
+            ActiveSupport::Notifications.subscribe(pattern) do |name, started, finished, id, payload|
+              event = ActiveSupport::Notifications::Event.new(name, started, finished, id, payload)
+              subscriber.call(event)
+            end
+          end
+        end
+
+        def detach!
+          Array(@subscriptions).each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+          @subscriptions = []
+        end
+
+        def subscriptions
+          Array(@subscriptions)
+        end
+      end
+
+      def call(event)
+        return if logger.nil?
+        return unless materialize?(event)
+
+        severity = severity_for(event)
+        logger.public_send(severity, log_entry(event))
+      rescue StandardError
+        begin
+          logger&.error({ event: "command_tower.logging.subscriber_failed", error_class: $!.class.name })
+        rescue StandardError
+          nil
+        end
+      end
+
+      def logger
+        self.class.logger
+      end
+
+      private
+
+      def materialize?(event)
+        name = event.name
+        return true if name.start_with?("command_tower.log.")
+        return true if name.start_with?("command_tower.messaging.")
+        return false unless name.start_with?("command_tower.lifecycle.")
+        return false if name.end_with?(".started")
+
+        outcome = (event.payload[:outcome] || event.payload["outcome"]).to_s
+        return true if %w[failure error].include?(outcome)
+
+        event.payload[:log_lifecycle] == true || event.payload["log_lifecycle"] == true
+      end
+
+      def log_entry(event)
+        CommandTower::Logging::Projection.call(event)
+      end
+
+      def severity_for(event)
+        name = event.name
+        if name.start_with?("command_tower.log.")
+          return named_severity(name.split(".").last)
+        end
+
+        payload_level = event.payload[:log_level] || event.payload["log_level"]
+        return named_severity(payload_level) if payload_level
+
+        return :debug if name.end_with?(".started")
+
+        outcome = event.payload[:outcome] || event.payload["outcome"]
+        return :error if outcome.to_s == "error"
+
+        :info
+      end
+
+      def named_severity(value)
+        level = value.to_sym
+        SEVERITIES.include?(level) ? level : :info
+      end
+    end
+  end
+end