command_tower 0.4.0 → 0.11.0

data/app/services/command_tower/identity/phone_verification/sms_transport/adapters/fake_adapter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      module SmsTransport
+        module Adapters
+          # In-memory / no-network adapter for tests and local default.
+          class FakeAdapter
+            class << self
+              attr_accessor :deliveries, :fail_with
+
+              def reset!
+                self.deliveries = []
+                self.fail_with = nil
+              end
+            end
+
+            self.reset!
+
+            def deliver(to:, body:)
+              if self.class.fail_with
+                code, message = self.class.fail_with
+                return SmsTransport::Result.new(success?: false, error_code: code, error_message: message)
+              end
+
+              self.class.deliveries << { to: to, body: body }
+              SmsTransport::Result.new(success?: true, error_code: nil, error_message: nil)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport/adapters/log_adapter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      module SmsTransport
+        module Adapters
+          # Logs masked destination only — never OTP body in production logs.
+          class LogAdapter
+            def deliver(to:, body:)
+              Rails.logger.info(
+                {
+                  event: "phone_verification_sms_log_adapter",
+                  to_masked: mask_phone(to),
+                  body_length: body.to_s.length
+                }.to_json
+              )
+              SmsTransport::Result.new(success?: true, error_code: nil, error_message: nil)
+            end
+
+            private
+
+            def mask_phone(value)
+              digits = value.to_s.gsub(/\D/, "")
+              return "[redacted]" if digits.length < 4
+
+              "#{"*" * (digits.length - 4)}#{digits[-4,]}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport/adapters/twilio_adapter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      module SmsTransport
+        module Adapters
+          # Smallest Twilio REST adapter. Requires Twilio credentials via
+          # CredentialResolution and identity.phone_verification.sms_from (or TWILIO_FROM).
+          class TwilioAdapter
+            def deliver(to:, body:)
+              twilio = CredentialResolution.resolve(:twilio)
+              account_sid = twilio.account_sid
+              auth_token = twilio.auth_token
+              from = CommandTower.config.identity.phone_verification.sms_from.presence ||
+                ENV["TWILIO_FROM"].to_s.presence ||
+                ENV["TWILIO_FROM_NUMBER"].to_s.presence
+
+              if account_sid.blank? || auth_token.blank? || from.blank?
+                return SmsTransport::Result.new(
+                  success?: false,
+                  error_code: :configuration_unavailable,
+                  error_message: "SMS provider is not configured"
+                )
+              end
+
+              uri = URI("https://api.twilio.com/2010-04-01/Accounts/#{account_sid}/Messages.json")
+              request = Net::HTTP::Post.new(uri)
+              request.basic_auth(account_sid, auth_token)
+              request.set_form_data("To" => to, "From" => from, "Body" => body)
+
+              response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+                http.request(request)
+              end
+
+              if response.is_a?(Net::HTTPSuccess)
+                SmsTransport::Result.new(success?: true, error_code: nil, error_message: nil)
+              else
+                SmsTransport::Result.new(
+                  success?: false,
+                  error_code: :provider_unavailable,
+                  error_message: "SMS provider rejected the request"
+                )
+              end
+            rescue StandardError
+              SmsTransport::Result.new(
+                success?: false,
+                error_code: :provider_unavailable,
+                error_message: "SMS provider unavailable"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/identity/phone_verification/sms_transport.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Identity
+    module PhoneVerification
+      # Vendor-agnostic SMS delivery for phone OTP. Identity depends on this interface only.
+      module SmsTransport
+        Result = Struct.new(:success?, :error_code, :error_message, keyword_init: true)
+
+        class << self
+          attr_writer :adapter
+
+          def adapter
+            @adapter ||= build_adapter
+          end
+
+          def reset_adapter!
+            @adapter = nil
+          end
+
+          def deliver(to:, body:)
+            adapter.deliver(to: to, body: body)
+          end
+
+          private
+
+          def build_adapter
+            name = CommandTower.config.identity.phone_verification.sms_adapter.to_s
+            case name
+            when "twilio"
+              Adapters::TwilioAdapter.new
+            when "log"
+              Adapters::LogAdapter.new
+            else
+              Adapters::FakeAdapter.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/jwt/authenticate_user.rb

@@ -1,86 +1,119 @@
 # frozen_string_literal: true
 
 module CommandTower::Jwt
-  class AuthenticateUser < CommandTower::ServiceBase
+  class AuthenticateUser
+    INVALID_TOKEN_MSG = "Unauthorized Access. Invalid Authorization token"
+    STALE_TOKEN_MSG = "Unauthorized Access. Token is no longer valid"
+    EMAIL_VERIFICATION_MSG = "Email must be verified to continue"
+    EMAIL_VERIFICATION_STATUS = 412
+
+    def self.call(token:, bypass_email_validation: false, with_reset: false)
+      new(token:, bypass_email_validation:, with_reset:).call
+    end
 
-    validate :token, is_a: String, required: true, sensitive: true
-    validate :bypass_email_validation, is_one: [true, false], default: false
-    validate :with_reset, is_one: [true, false], default: false
+    def initialize(token:, bypass_email_validation: false, with_reset: false)
+      @token = token
+      @bypass_email_validation = !!bypass_email_validation
+      @with_reset = !!with_reset
+    end
 
     def call
-      result = Decode.(token:)
+      decoded = Decode.(token:)
+      return invalid_token if decoded.failure?
 
-      if result.failure?
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
-      end
-      payload = result.payload
+      payload = decoded.payload
 
-      expires_at = validate_generated_at!(generated_at: payload[:generated_at])
+      expires_at = expires_at_for(generated_at: payload[:generated_at])
+      return invalid_token if expires_at.nil?
 
-      user = User.find(payload[:user_id]) rescue nil
+      user = User.find_by(id: payload[:user_id])
       if user.nil?
         log_warn("user_id [#{payload[:user_id]}] was not found. Cannot Continue")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return invalid_token
       end
 
-      if user.verifier_token == payload[:verifier_token]
-        context.user = user
-      else
-        context.fail!(msg: "Unauthorized Access. Token is no longer valid")
+      unless user.verifier_token == payload[:verifier_token]
+        return AuthenticationOutcome.failure(msg: STALE_TOKEN_MSG)
       end
 
-      email_validation_required!(user:)
+      if email_validation_required?(user:)
+        return AuthenticationOutcome.failure(
+          msg: EMAIL_VERIFICATION_MSG,
+          status: EMAIL_VERIFICATION_STATUS,
+          user:
+        )
+      end
 
+      generated_token = nil
+      impersonation_session_id = payload[:impersonation_session_id].presence
       if with_reset
-        context.generated_token = CommandTower::Jwt::LoginCreate.(user:).token
+        generated_token = LoginCreate.(user:, impersonation_session_id:).token
         expires_at = CommandTower.config.jwt.ttl.from_now.to_time
       end
 
-      context.expires_at = expires_at.to_s
+      AuthenticationOutcome.success(
+        user:,
+        expires_at: expires_at.to_s,
+        generated_token:,
+        impersonation_session_id:
+      )
     end
 
-    def validate_generated_at!(generated_at:)
+    private
+
+    attr_reader :token, :bypass_email_validation, :with_reset
+
+    def invalid_token
+      AuthenticationOutcome.failure(msg: INVALID_TOKEN_MSG)
+    end
+
+    # Returns nil when the token cannot be trusted to carry a usable expiration.
+    def expires_at_for(generated_at:)
       if generated_at.nil?
         log_warn("generated_at payload is missing from the JWT token. Cannot continue")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return nil
       end
 
       expires_time = begin
-        time = Time.at(generated_at)
-        time + CommandTower.config.jwt.ttl
-      rescue
+        Time.at(generated_at) + CommandTower.config.jwt.ttl
+      rescue StandardError
         nil
       end
 
       if expires_time.nil?
         log_warn("generated_at payload cannot be parsed. Cannot continue")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return nil
       end
 
       if expires_time < Time.now
         log_warn("generated_at is no longer valid. Must request new token")
-        context.fail!(msg: "Unauthorized Access. Invalid Authorization token")
+        return nil
       end
 
       expires_time
     end
 
-    def email_validation_required!(user:)
-      return unless CommandTower.config.login.plain_text.email_verify?
+    def email_validation_required?(user:)
+      return false unless CommandTower.config.login.plain_text.email_verify?
 
       if bypass_email_validation
         log_info("Bypassing email validation without checking if user should be able to continue")
-        return
+        return false
       end
 
-      return if user.email_validated
+      return false if user.email_validated
 
       log_info("User's email is not yet validated.")
-      result = CommandTower::LoginStrategy::PlainText::EmailVerification::Required.(user:)
 
-      if result.required
-        context.fail!(msg: "User's Email must be validated before they can continue")
-      end
+      CommandTower::LoginStrategy::PlainText::EmailVerification::Required.(user:).required?
+    end
+
+    def log_info(msg)
+      Rails.logger.info { "[#{self.class.name}] #{msg}" }
+    end
+
+    def log_warn(msg)
+      Rails.logger.warn { "[#{self.class.name}] #{msg}" }
     end
   end
 end

data/app/services/command_tower/jwt/authentication_outcome.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CommandTower::Jwt
+  # Narrow value object describing the result of AuthenticateUser only.
+  # This is deliberately not a platform result type — do not reuse it elsewhere.
+  class AuthenticationOutcome
+    attr_reader :user, :expires_at, :generated_token, :status, :msg, :impersonation_session_id
+
+    def self.success(user:, expires_at:, generated_token: nil, impersonation_session_id: nil)
+      new(success: true, user:, expires_at:, generated_token:, impersonation_session_id:)
+    end
+
+    # `user` is carried on failures so callers can distinguish a known user who
+    # is blocked (e.g. email verification required) from an unidentified caller.
+    def self.failure(msg:, status: nil, user: nil)
+      new(success: false, msg:, status:, user:)
+    end
+
+    def initialize(success:, user: nil, expires_at: nil, generated_token: nil, status: nil, msg: nil, impersonation_session_id: nil)
+      @success = success
+      @user = user
+      @expires_at = expires_at
+      @generated_token = generated_token
+      @status = status
+      @msg = msg
+      @impersonation_session_id = impersonation_session_id
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !@success
+    end
+  end
+end

data/app/services/command_tower/jwt/decode.rb

@@ -3,19 +3,38 @@
 require "jwt"
 
 module CommandTower::Jwt
-  class Decode < CommandTower::ServiceBase
+  class Decode
+    ALGORITHM = "HS256"
 
-    validate :token, is_a: String, required: true, sensitive: true
+    DecodeOutcome = Data.define(:success, :payload, :headers, :msg) do
+      def self.success(payload:, headers: nil)
+        new(success: true, payload:, headers:, msg: nil)
+      end
 
-    def call
-      data = JWT.decode(token, CommandTower.config.jwt.hmac_secret, true, { algorithm: "HS256" })
+      def self.failure(msg:)
+        new(success: false, payload: nil, headers: nil, msg:)
+      end
 
-      context.payload = data[0].with_indifferent_access
-      context.headers = data[1].with_indifferent_access
+      def success?
+        success
+      end
+
+      def failure?
+        !success
+      end
+    end
+
+    def self.call(token:)
+      data = JWT.decode(token, CommandTower.config.jwt.hmac_secret, true, { algorithm: ALGORITHM })
+
+      DecodeOutcome.success(
+        payload: data[0].with_indifferent_access,
+        headers: data[1].with_indifferent_access
+      )
     rescue JWT::DecodeError => e
-      log_error(e)
+      Rails.logger.warn { "[#{name}] Failed to decode token: #{e.class.name}" }
 
-      context.fail!(msg: "Invalid Token")
+      DecodeOutcome.failure(msg: "Invalid Token")
     end
   end
 end

data/app/services/command_tower/jwt/encode.rb

@@ -3,13 +3,11 @@
 require "jwt"
 
 module CommandTower::Jwt
-  class Encode < CommandTower::ServiceBase
+  class Encode
+    ALGORITHM = "HS256"
 
-    validate :payload, is_a: Hash, required: true
-    validate :header, is_a: Hash, required: false
-
-    def call
-      context.token = JWT.encode(payload, CommandTower.config.jwt.hmac_secret, "HS256", header || {})
+    def self.call(payload:, header: nil)
+      JWT.encode(payload, CommandTower.config.jwt.hmac_secret, ALGORITHM, header || {})
     end
   end
 end

data/app/services/command_tower/jwt/login_create.rb

@@ -1,21 +1,23 @@
 # frozen_string_literal: true
 
 module CommandTower::Jwt
-  class LoginCreate < CommandTower::ServiceBase
-    on_argument_validation :fail_early
+  class LoginCreate
+    IssuedToken = Data.define(:token)
 
-    validate :user, is_a: User, required: true
-
-    def call
-      context.token = Encode.(payload:).token
+    def self.call(user:, impersonation_session_id: nil)
+      IssuedToken.new(token: Encode.(payload: payload_for(user, impersonation_session_id:)))
     end
 
-    def payload
-      {
+    def self.payload_for(user, impersonation_session_id: nil)
+      payload = {
         generated_at: Time.now.to_i,
         user_id: user.id,
         verifier_token: user.retreive_verifier_token!,
       }
+      token = impersonation_session_id.to_s.strip
+      payload[:impersonation_session_id] = token unless token.empty?
+      payload
     end
+    private_class_method :payload_for
   end
 end

data/app/services/command_tower/login_strategy/plain_text/email_verification/required.rb

@@ -1,20 +1,22 @@
 # frozen_string_literal: true
 
 module CommandTower::LoginStrategy::PlainText::EmailVerification
-  class Required < CommandTower::ServiceBase
-    validate :user, is_a: User, required: true
-
-    def call
-      context.reqired_after_time = reqired_after_time
-      context.required = Time.now > reqired_after_time
+  # Decides whether an unverified account has passed its grace period and must
+  # verify before it can keep authenticating.
+  class Required
+    Requirement = Data.define(:required, :required_after_time) do
+      def required? = required
     end
 
-    def reqired_after_time
-      user.created_at + email_verify.verify_email_required_within
+    def self.call(user:)
+      required_after_time = user.created_at + email_verify.verify_email_required_within
+
+      Requirement.new(required: Time.now > required_after_time, required_after_time:)
     end
 
-    def email_verify
+    def self.email_verify
       CommandTower.config.login.plain_text.email_verify
     end
+    private_class_method :email_verify
   end
 end

data/app/services/command_tower/messaging/accept/channel_delivery_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      ChannelDeliveryResult = Data.define(:id, :channel_key, :status) do
+        def self.build(id:, channel_key:, status:)
+          new(id:, channel_key: channel_key.to_s, status: status.to_s).freeze
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/accept/coordinator.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Accept
+      # Domain orchestrator under Produce: validate → idempotency → plan → persist → schedule handoff.
+      # Not an ApplicationWorkflow (nested AW under Produce/host workflows is forbidden).
+      class Coordinator
+        def self.call(**kwargs)
+          new(**kwargs).call
+        end
+
+        def initialize(
+          recipient_id:,
+          notification_type_key:,
+          host_event_identity:,
+          title:,
+          body:,
+          metadata: nil,
+          preference_state: nil,
+          platform_enabled_channels:,
+          message_overrides: nil
+        )
+          @recipient_id = recipient_id
+          @notification_type_key = notification_type_key
+          @host_event_identity = host_event_identity
+          @title = title
+          @body = body
+          @metadata = metadata
+          @preference_state = preference_state
+          @platform_enabled_channels = platform_enabled_channels
+          @message_overrides = message_overrides
+        end
+
+        def call
+          request = {
+            recipient_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+            host_event_identity: @host_event_identity,
+            title: @title,
+            body: @body,
+            metadata: @metadata,
+            preference_state: @preference_state,
+            platform_enabled_channels: @platform_enabled_channels,
+            message_overrides: @message_overrides,
+          }
+
+          OperationLogger.around(request:) do
+            validate_request!
+            fingerprint = RequestNormalizer.fingerprint(
+              title: @title,
+              body: @body,
+              metadata: @metadata,
+              preference_state: @preference_state,
+              platform_enabled_channels: @platform_enabled_channels,
+              message_overrides: @message_overrides,
+            )
+
+            existing = find_by_namespace
+            if existing
+              return resolve_existing(existing, fingerprint)
+            end
+
+            plan = plan!
+            persist_new!(request:, plan:, fingerprint:)
+          end
+        end
+
+        private
+
+        def validate_request!
+          errors = []
+          errors << "recipient_id is required" if blank?(@recipient_id)
+          errors << "notification_type_key is required" if blank?(@notification_type_key)
+          errors << "host_event_identity is required" if blank?(@host_event_identity)
+          errors << "title is required" if blank?(@title)
+          errors << "body is required" if blank?(@body)
+          if @platform_enabled_channels.nil?
+            errors << "platform_enabled_channels is required"
+          end
+          unless @preference_state.nil?
+            errors << "preference_state must not be supplied; CommandTower loads stored preferences"
+          end
+
+          raise ValidationError, errors.join("; ") if errors.any?
+        end
+
+        def blank?(value)
+          value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
+            (value.is_a?(String) && value.strip.empty?)
+        end
+
+        def find_by_namespace
+          Messaging::Communication.find_by_idempotency_namespace(
+            user_id: @recipient_id,
+            notification_type_key: @notification_type_key,
+            host_event_identity: @host_event_identity,
+          )
+        end
+
+        def resolve_existing(communication, fingerprint)
+          if communication.accept_request_fingerprint == fingerprint
+            return Result.from_communication(
+              reload_aggregate(communication.id),
+              idempotent_replay: true,
+            )
+          end
+
+          raise IdempotencyConflictError,
+                "idempotency namespace already accepted with a different request"
+        end
+
+        def plan!
+          Planner.plan(
+            notification_type_key: @notification_type_key,
+            recipient_id: @recipient_id,
+            preference_state: nil,
+            platform_enabled_channels: @platform_enabled_channels,
+            message_overrides: @message_overrides,
+          )
+        rescue Planner::UnknownTypeError => e
+          raise UnknownTypeError, e.message
+        rescue Planner::IllegalOverrideError => e
+          raise IllegalOverrideError, e.message
+        rescue Planner::ImpossibleMandatoryPlanError => e
+          raise ImpossibleMandatoryPlanError, e.message
+        rescue Planner::InvalidEvaluationError => e
+          raise InvalidPreferenceError, e.message
+        rescue Preferences::InvalidPreferenceStateError => e
+          raise InvalidPreferenceError, e.message
+        rescue Preferences::StoreError => e
+          raise PersistenceError, e.message
+        rescue Preferences::UnknownTypeError => e
+          raise UnknownTypeError, e.message
+        end
+
+        def persist_new!(request:, plan:, fingerprint:)
+          communication = Persister.call(request:, plan:, fingerprint:)
+          HandoffScheduler.schedule_after_commit(communication.id)
+          Result.from_communication(communication, idempotent_replay: false)
+        rescue ActiveRecord::RecordNotUnique => error
+          resolve_record_not_unique!(error, fingerprint)
+        rescue ActiveRecord::RecordInvalid => e
+          raise PersistenceError, e.message
+        end
+
+        def resolve_record_not_unique!(error, fingerprint)
+          existing = find_by_namespace
+          if existing
+            return resolve_existing(existing, fingerprint)
+          end
+
+          raise PersistenceError, "persistence uniqueness failure"
+        end
+
+        def reload_aggregate(id)
+          Messaging::Communication.includes(
+            :destination_plan,
+            :inbox_item,
+            :channel_deliveries,
+          ).find(id)
+        end
+      end
+    end
+  end
+end