command_tower 0.3.1 → 0.10.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/password_recovery/authorization_helper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module PasswordRecovery
+    module AuthorizationHelper
+      SCHEME = "Recovery"
+      HEADER = "Authorization"
+
+      module_function
+
+      def extract_token(request)
+        raw = request.headers[HEADER].to_s.strip
+        return { error: :missing } if raw.blank?
+
+        match = raw.match(/\A#{SCHEME}\s+(.+)\z/i)
+        return { error: :invalid_format } unless match
+
+        token = match[1].to_s.strip
+        return { error: :missing } if token.blank?
+
+        { token: token }
+      end
+    end
+  end
+end

data/lib/command_tower/redis_connection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "redis"
+
+module CommandTower
+  module RedisConnection
+    module_function
+
+    def current
+      @current ||= Redis.new(url: ENV.fetch("REDIS_URL"))
+    end
+
+    def with
+      yield current
+    end
+
+    def reset!
+      @current = nil
+    end
+  end
+end

data/lib/command_tower/schema/error/email_validation_required.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "json_schematize/generator"
+
+module CommandTower
+  module Schema
+    module Error
+      class EmailValidationRequired < JsonSchematize::Generator
+        add_field name: :status, type: String
+        add_field name: :message, type: String
+        add_field name: :meta, type: Hash
+      end
+    end
+  end
+end

data/lib/command_tower/schema/shared/user.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Schema
+    module Shared
+      class User < JsonSchematize::Generator
+        schema_default option: :dig_type, value: :string
+
+        def self.convert_user_object(user:)
+          attributes = CommandTower.config.user.default_attributes.map(&:to_s)
+          object = user.attributes.slice(*attributes)
+
+          new(object)
+        end
+
+        # Gets assigned during configuration phase via
+        # lib/command_tower/configuration/user/config.rb
+        def self.assign!
+          attributes = CommandTower.config.user.default_attributes
+
+          attributes.each do |attribute|
+            if metadata = ::User.attribute_to_type_mapping[attribute]
+              type = metadata[:serialized_type] ? metadata[:serialized_type] : metadata[:base]
+              type = JsonSchematize::Boolean if type == "Boolean"
+              add_field(name: attribute, type:)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/schema.rb

@@ -7,32 +7,9 @@ module CommandTower
 
     ## Generic Error Schemas
     require "command_tower/schema/error/base"
+    require "command_tower/schema/error/email_validation_required"
     require "command_tower/schema/error/invalid_argument_response"
 
-    ## Plain Text Controller
-    require "command_tower/schema/plain_text/create_user_response"
-    require "command_tower/schema/plain_text/create_user_request"
-
-    require "command_tower/schema/plain_text/email_verify_request"
-    require "command_tower/schema/plain_text/email_verify_response"
-
-    require "command_tower/schema/plain_text/email_verify_send_response"
-    require "command_tower/schema/plain_text/email_verify_send_request"
-
-    require "command_tower/schema/plain_text/login_request"
-    require "command_tower/schema/plain_text/login_response"
-
-    require "command_tower/schema/admin/users"
-
-    require "command_tower/schema/user"
-    require "command_tower/schema/page"
-
-    require "command_tower/schema/inbox/metadata"
-    require "command_tower/schema/inbox/message_entity"
-    require "command_tower/schema/inbox/modified"
-    require "command_tower/schema/inbox/blast_response"
-    require "command_tower/schema/inbox/blast_request"
-    require "command_tower/schema/inbox/message_blast_entity"
-    require "command_tower/schema/inbox/message_blast_metadata"
+    require "command_tower/schema/shared/user"
   end
 end

data/lib/command_tower/signup/authorization_helper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Signup
+    module AuthorizationHelper
+      SCHEME = "Signup"
+      HEADER = "Authorization"
+
+      module_function
+
+      def extract_token(request)
+        raw = request.headers[HEADER].to_s.strip
+        return { error: :missing } if raw.blank?
+
+        match = raw.match(/\A#{SCHEME}\s+(.+)\z/i)
+        return { error: :invalid_format } unless match
+
+        token = match[1].to_s.strip
+        return { error: :missing } if token.blank?
+
+        { token: token }
+      end
+    end
+  end
+end