command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module PrincipalCapabilities
+    class Error < CommandTower::Error; end
+
+    class UnregisteredCapabilityError < Error; end
+    class DuplicateCapabilityError < Error; end
+    class HostOverrideError < Error; end
+    class InvalidCapabilityNameError < Error; end
+    class InvalidCapabilityDefinitionError < Error; end
+    class MissingRequiredEntityError < Error; end
+    class FrozenRegistryError < Error; 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

data/lib/command_tower/spec_helper.rb

@@ -8,12 +8,69 @@ module CommandTower
         token = result.token
       end
 
-      @request.headers[CommandTower::ApplicationController::AUTHENTICATION_HEADER] = "Bearer: #{token}"
+      @request.headers[CommandTower::ApplicationController::AUTHENTICATION_HEADER] = "Bearer #{token}"
       @request.headers[CommandTower::ApplicationController::AUTHENTICATION_WITH_RESET] = "true" if with_reset
     end
 
     def unset_jwt_token!
       @request.headers[CommandTower::ApplicationController::AUTHENTICATION_HEADER] = nil
     end
+
+    # Helper method to get login token and cookie value
+    # Uses the login service directly to avoid controller double render issues
+    # @param user [User] The user to login
+    # @param password [String] The user's password
+    # @return [Hash] Hash with :token, :cookie_value, and :cookie_header
+    def get_login_token_and_cookie(user:, password:)
+      # Authenticate user first
+      result = CommandTower::Services::Auth::PlainText::Login.(identifier: user.username, password:)
+      raise "Login failed: #{result.errors.map(&:code).join(", ")}" unless result.success?
+
+      token = result.data[:token]
+      expires_at = CommandTower.config.jwt.ttl.from_now.to_time.to_s
+      cookie_name = CommandTower.config.jwt.cookie.name
+
+      # Create a mock response to set cookie
+      mock_response = ActionDispatch::TestResponse.new
+      CommandTower::Jwt::AuthorizationHelper.set_token(mock_response, token, expires_at: expires_at)
+      cookie_header = mock_response.headers["Set-Cookie"]
+      cookie_value = cookie_header&.match(/#{cookie_name}=([^;]+)/)&.[](1)
+
+      { token:, cookie_value:, cookie_header: }
+    end
+
+    # Helper to set CSRF cookie in request
+    def set_csrf_cookie!(token)
+      csrf_cookie_name = CommandTower.config.jwt.cookie.csrf.cookie_name
+      @request.cookies[csrf_cookie_name] = token
+    end
+
+    # Helper to set CSRF header in request
+    def set_csrf_header!(token)
+      csrf_header_name = CommandTower.config.jwt.cookie.csrf.header_name
+      @request.headers[csrf_header_name] = token
+    end
+
+    # Helper to extract CSRF cookie from response
+    def extract_csrf_cookie(response)
+      csrf_cookie_name = CommandTower.config.jwt.cookie.csrf.cookie_name
+      set_cookie_header = response.headers["Set-Cookie"]
+      return nil unless set_cookie_header
+
+      # Handle both string and array (when multiple cookies are set)
+      cookie_headers = set_cookie_header.is_a?(Array) ? set_cookie_header : [set_cookie_header]
+
+      cookie_headers.each do |header|
+        match = header.match(/#{csrf_cookie_name}=([^;]+)/)
+        return match[1] if match
+      end
+      nil
+    end
+
+    # Helper to get CSRF cookie value from request
+    def get_csrf_cookie_value
+      csrf_cookie_name = CommandTower.config.jwt.cookie.csrf.cookie_name
+      @request.cookies[csrf_cookie_name]
+    end
   end
 end

data/lib/command_tower/testing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module CommandTower
+  # Explicit host/test entry for shared FactoryBot definitions and related
+  # testing bootstrap. Not loaded in production via Railtie.
+  module Testing
+    class << self
+      # Preferred host entry. Currently loads factories; reserved for future
+      # shared testing setup (helpers, config checks).
+      def install!
+        load_factories!
+      end
+
+      # Load CommandTower FactoryBot definitions exactly once.
+      # Loads files under Engine.root/spec/factories explicitly (does not mutate
+      # global definition_file_paths / find_definitions).
+      def load_factories!
+        return if factories_loaded?
+
+        begin
+          require "factory_bot"
+        rescue LoadError
+          raise LoadError,
+                "CommandTower::Testing requires the factory_bot gem. " \
+                "Add `factory_bot` or `factory_bot_rails` to your host test group."
+        end
+
+        factory_files.each { |path| Kernel.load(path) }
+        @factories_loaded = true
+        true
+      end
+
+      def factories_loaded?
+        @factories_loaded == true
+      end
+
+      # Reset loader state (specs only). Does not undefine FactoryBot factories.
+      def reset_factories_loaded_flag!
+        @factories_loaded = false
+      end
+
+      # Ensures COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET for endpoint factories
+      # in non-production test environments when unset.
+      def ensure_endpoint_secret!
+        return unless ENV["COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET"].to_s.empty?
+
+        ENV["COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET"] =
+          "test-messaging-endpoint-secret-not-for-production"
+      end
+
+      def factories_path
+        CommandTower::Engine.root.join("spec/factories")
+      end
+
+      private
+
+      def factory_files
+        Dir[factories_path.join("**/*.rb").to_s].sort
+      end
+    end
+  end
+end

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.4.0"
+  VERSION = "0.11.0"
 end

data/lib/command_tower.rb

@@ -1,8 +1,29 @@
 require "command_tower/error"
+require "command_tower/current"
+require "command_tower/execution"
+require "command_tower/events"
+require "command_tower/audit"
+require "command_tower/impersonation/activity_declaration"
+require "command_tower/impersonation/apply_overlay"
+require "command_tower/impersonation/clear_overlay_for_audit"
+require "command_tower/impersonation/establish_identity"
+require "command_tower/admin_workspace"
+require "command_tower/admin_scope"
+require "command_tower/logging/lifecycle_declaration"
+require "command_tower/logging/projection"
+require "command_tower/logging/subscriber"
 
 require "command_tower/version"
 require "command_tower/engine"
 require "command_tower/configuration/config"
+require "command_tower/install/baseline"
+require "command_tower/install/doctor"
+require "command_tower/credential_resolution"
+require "command_tower/jwt/authorization_helper"
+require "command_tower/jwt/csrf_helper"
+require "command_tower/password_recovery/authorization_helper"
+require "command_tower/redis_connection"
+require "command_tower/signup/authorization_helper"
 
 module CommandTower
   def self.config
@@ -11,6 +32,7 @@ module CommandTower
 
   def self.configure
     yield(config)
+    CredentialResolution::SmtpActionMailerBridge.apply!
   end
 
   def self.config=(configuration)
@@ -19,6 +41,16 @@ module CommandTower
     @config = configuration
   end
 
+  # Optional custom credential resolver (#resolve(provider) → typed credentials).
+  # Precedence: config.credentials.* → credential_resolver → ENV.
+  def self.credential_resolver
+    @credential_resolver
+  end
+
+  def self.credential_resolver=(resolver)
+    @credential_resolver = resolver
+  end
+
   def self.app_name
     Proc === config.app.app_name ? config.app.app_name.() : config.app.app_name
   end

data/lib/generators/command_tower/configure/USAGE

@@ -1,8 +1,20 @@
 Description:
-    Creates a default Configuration file for the ApiBaseEngine.
+    Creates a default CommandTower initializer and optionally mounts the engine.
+
+    Prefer the productized install entry point for new hosts:
+
+        bin/rails command_tower:install
+        bin/rails db:migrate
+
+    This generator is still available for initializer/route scaffolding alone.
 
 Example:
     bin/rails generate command_tower:configure
+    bin/rails generate command_tower:configure --skip-routes
+    bin/rails generate command_tower:configure --force
 
-    This will create:
+    This will create (unless already present without --force):
         config/initializers/command_tower.rb
+
+    And mount (unless --skip-routes or already mounted):
+        mount CommandTower::Engine => "/"

data/lib/generators/command_tower/configure/configure_generator.rb

@@ -1,12 +1,39 @@
+# frozen_string_literal: true
+
 class CommandTower::ConfigureGenerator < Rails::Generators::Base
   source_root File.expand_path("templates", __dir__)
 
+  class_option :skip_routes,
+    type: :boolean,
+    default: false,
+    desc: "Do not mount CommandTower::Engine in config/routes.rb"
+
+  class_option :force,
+    type: :boolean,
+    default: false,
+    desc: "Overwrite an existing config/initializers/command_tower.rb"
+
   def create_config_file
-    create_file Rails.root.join("config", "initializers", "command_tower.rb"),
+    relative = "config/initializers/command_tower.rb"
+    path = File.join(destination_root, relative)
+    if File.exist?(path) && !options[:force]
+      say_status :skip, "#{relative} (already present; pass --force to overwrite)", :yellow
+      return
+    end
+
+    create_file relative,
       CommandTower.config.class.composer_generate_config(wrapping: "CommandTower.configure", require_file: "command_tower")
   end
 
   def create_route
-    route "mount CommandTower::Engine => \"/\""
+    return if options[:skip_routes]
+
+    routes_path = File.join(destination_root, "config/routes.rb")
+    if File.exist?(routes_path) && File.read(routes_path).include?("CommandTower::Engine")
+      say_status :skip, "config/routes.rb (CommandTower::Engine already mounted)", :yellow
+      return
+    end
+
+    route 'mount CommandTower::Engine => "/"'
   end
 end

data/lib/tasks/auto_annotate_models.rake

@@ -2,59 +2,27 @@
 # NOTE: are sensitive to local FS writes, and besides -- it's just not proper
 # NOTE: to have a dev-mode tool do its thing in production.
 
-# if Rails.env.development?
-  require 'annotate'
-  task :set_annotation_options do
-    # You can override any of these by setting an environment variable of the
-    # same name.
-    Annotate.set_defaults(
-      'active_admin'                => 'false',
-      'additional_file_patterns'    => [],
-      'routes'                      => 'false',
-      'models'                      => 'true',
-      'position_in_routes'          => 'before',
-      'position_in_class'           => 'before',
-      'position_in_test'            => 'before',
-      'position_in_fixture'         => 'before',
-      'position_in_factory'         => 'before',
-      'position_in_serializer'      => 'before',
-      'show_foreign_keys'           => 'true',
-      'show_complete_foreign_keys'  => 'false',
-      'show_indexes'                => 'true',
-      'simple_indexes'              => 'false',
-      'model_dir'                   => 'app/models',
-      'root_dir'                    => '',
-      'include_version'             => 'false',
-      'require'                     => '',
-      'exclude_tests'               => 'false',
-      'exclude_fixtures'            => 'false',
-      'exclude_factories'           => 'false',
-      'exclude_serializers'         => 'false',
-      'exclude_scaffolds'           => 'true',
-      'exclude_controllers'         => 'true',
-      'exclude_helpers'             => 'true',
-      'exclude_sti_subclasses'      => 'false',
-      'ignore_model_sub_dir'        => 'false',
-      'ignore_columns'              => nil,
-      'ignore_routes'               => nil,
-      'ignore_unknown_models'       => 'false',
-      'hide_limit_column_types'     => 'integer,bigint,boolean',
-      'hide_default_column_types'   => 'json,jsonb,hstore',
-      'skip_on_db_migrate'          => 'false',
-      'format_bare'                 => 'true',
-      'format_rdoc'                 => 'false',
-      'format_yard'                 => 'false',
-      'format_markdown'             => 'false',
-      'sort'                        => 'false',
-      'force'                       => 'false',
-      'frozen'                      => 'false',
-      'classified_sort'             => 'true',
-      'trace'                       => 'false',
-      'wrapper_open'                => nil,
-      'wrapper_close'               => nil,
-      'with_comment'                => 'true'
-    )
-  end
+# Engine rake layout exposes annotate as app:annotate_models; skip auto-hook on
+# db:migrate so migrate does not fail looking for top-level annotate_models.
+# Annotate is a CommandTower *development* dependency of the gem repo, not a
+# runtime dependency for downstream hosts — guard the require.
+if Rails.env.development?
+  begin
+    require "annotate"
+  rescue LoadError
+    # Host applications without the annotate gem skip model annotation hooks.
+  else
+    task :set_annotation_options do
+      Annotate.set_defaults(
+        "active_admin" => "false",
+        "models" => "true",
+        "model_dir" => "app/models",
+        "skip_on_db_migrate" => "true",
+        "show_foreign_keys" => "true",
+        "show_indexes" => "true"
+      )
+    end
 
-  Annotate.load_tasks
-# end
+    Annotate.load_tasks
+  end
+end

data/lib/tasks/install.rake

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "command_tower/install/doctor"
+
+namespace :command_tower do
+  desc "Install CommandTower into the host (migrations + optional configure). Does not run db:migrate."
+  task install: :environment do
+    puts
+    puts "=== CommandTower install ==="
+    puts
+
+    puts "→ Installing engine migrations (Rails-native)…"
+    Rake::Task["command_tower:install:migrations"].reenable
+    Rake::Task["command_tower:install:migrations"].invoke
+    puts
+
+    skip_configure = %w[1 true yes].include?(ENV["SKIP_CONFIGURE"].to_s.downcase)
+    if skip_configure
+      puts "→ Skipping configure generator (SKIP_CONFIGURE=#{ENV['SKIP_CONFIGURE']})"
+    else
+      puts "→ Generating initializer / routes (command_tower:configure)…"
+      require "rails/generators"
+      generator_args = []
+      generator_args << "--skip-routes" if %w[1 true yes].include?(ENV["SKIP_MOUNT"].to_s.downcase)
+      generator_args << "--force" if %w[1 true yes].include?(ENV["FORCE"].to_s.downcase)
+      Rails::Generators.invoke("command_tower:configure", generator_args)
+    end
+
+    puts
+    puts "=== Next steps ==="
+    puts "  1. Review config/initializers/command_tower.rb (required secrets, optional features)."
+    puts "  2. bin/rails db:migrate"
+    puts "  3. bin/rails command_tower:doctor"
+    puts "  4. Optionally: bin/rails command_tower:users:create"
+    puts
+    puts "Docs: see the CommandTower gem docs/initializing.md (packaged with the gem)."
+    puts "Upgrades: bump the gem, then bin/rails command_tower:install:migrations && bin/rails db:migrate"
+    puts "           (or: SKIP_CONFIGURE=1 bin/rails command_tower:install)."
+    puts
+  end
+
+  desc "Validate CommandTower host setup (secrets, migrations, Rails version)"
+  task doctor: :environment do
+    require "command_tower/install/doctor"
+
+    puts
+    puts "=== CommandTower doctor ==="
+    puts
+
+    findings = CommandTower::Install::Doctor.new.run
+    failures = 0
+    warnings = 0
+
+    findings.each do |finding|
+      icon =
+        case finding.severity
+        when :pass then "[pass]"
+        when :warn then "[warn]"
+        when :fail then "[fail]"
+        else "[????]"
+        end
+
+      failures += 1 if finding.severity == :fail
+      warnings += 1 if finding.severity == :warn
+
+      puts "#{icon} #{finding.message}"
+      puts "       → #{finding.remediation}" if finding.remediation
+    end
+
+    puts
+    if failures.positive?
+      puts "Doctor found #{failures} failure(s) and #{warnings} warning(s)."
+      abort("CommandTower doctor failed")
+    elsif warnings.positive?
+      puts "Doctor passed with #{warnings} warning(s)."
+    else
+      puts "Doctor passed."
+    end
+    puts
+  end
+end