command_tower 0.3.1 → 0.10.0

data/app/services/command_tower/messaging/endpoints/create.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      # Local persist only. Never contacts providers (Pushover Transport included).
+      class Create
+        def self.call(owner_user_id:, channel_key:, address: nil, credentials: nil)
+          new(owner_user_id:, channel_key:, address:, credentials:).call
+        end
+
+        def initialize(owner_user_id:, channel_key:, address:, credentials:)
+          @owner_user_id = owner_user_id
+          @channel_key = channel_key.to_s
+          @address = address
+          @credentials = credentials
+        end
+
+        def call
+          ChannelGate.assert_endpoint_backed!(@channel_key)
+
+          if Endpoint.typed_credentials_channel?(@channel_key)
+            create_typed_credentials
+          else
+            create_address_backed
+          end
+        end
+
+        private
+
+        def create_typed_credentials
+          assert_pushover_credentials_contract!
+
+          validated = Validators.validate_pushover_credentials!(@credentials)
+          attrs = Persistence.build_pushover_parent_attrs(validated:)
+          fingerprint = attrs.fetch(:address_fingerprint)
+
+          existing = Persistence.find_active_by_fingerprint(
+            owner_user_id: @owner_user_id,
+            channel_key: @channel_key,
+            fingerprint:,
+          )
+          if existing
+            return resolve_idempotent_pushover(existing, validated)
+          end
+
+          assert_no_other_single_active!
+
+          insert_pushover(attrs, fingerprint, validated)
+        end
+
+        def create_address_backed
+          assert_address_contract!
+
+          validated = Validators.validate!(channel_key: @channel_key, address: @address)
+          attrs = Persistence.build_encrypted_attrs(
+            normalized_address: validated.normalized_address,
+            masked_display_value: validated.masked_display_value,
+          )
+          fingerprint = attrs.fetch(:address_fingerprint)
+
+          existing = Persistence.find_active_by_fingerprint(
+            owner_user_id: @owner_user_id,
+            channel_key: @channel_key,
+            fingerprint:,
+          )
+          return SafeView.from_record(existing) if existing
+
+          assert_no_other_single_active!
+
+          insert_address_backed(attrs, fingerprint)
+        end
+
+        def assert_pushover_credentials_contract!
+          if @address.present?
+            raise ValidationError, "pushover create requires credentials: and must not pass address:"
+          end
+          if @credentials.nil?
+            raise ValidationError, "pushover create requires credentials: with user_key and application_token"
+          end
+        end
+
+        def assert_address_contract!
+          if @credentials.present?
+            raise ValidationError, "channel #{@channel_key.inspect} does not accept credentials:"
+          end
+          if @address.nil?
+            raise ValidationError, "address must be present"
+          end
+        end
+
+        def assert_no_other_single_active!
+          return unless Endpoint.single_active_channel?(@channel_key)
+
+          other = Endpoint.active.for_owner(@owner_user_id).for_channel(@channel_key).first
+          return if other.nil?
+
+          if Endpoint.typed_credentials_channel?(@channel_key)
+            raise ConflictError,
+                  "an active endpoint already exists for this owner and channel with different credentials; use replace"
+          end
+
+          raise ConflictError,
+                "an active endpoint already exists for this owner and channel; use replace"
+        end
+
+        def resolve_idempotent_pushover(existing, validated)
+          stored = SecretReader.read_pushover_credentials!(
+            owner_user_id: @owner_user_id,
+            endpoint_id: existing.id,
+          )
+          same_pair =
+            stored.fetch(:user_key) == validated.normalized_user_key &&
+            stored.fetch(:application_token) == validated.normalized_application_token
+
+          return SafeView.from_record(existing) if same_pair
+
+          raise ConflictError,
+                "an active endpoint already exists for this owner and channel with different credentials; use replace"
+        end
+
+        def insert_pushover(attrs, fingerprint, validated)
+          Endpoint.transaction do
+            record = Endpoint.new(
+              user_id: @owner_user_id,
+              channel_key: @channel_key,
+              lifecycle_state: "active",
+              verification_state: "unverified",
+              **attrs,
+            )
+            record.derive_uniqueness_columns!
+            record.save!
+            Persistence.create_pushover_credential!(endpoint: record, validated:)
+            SafeView.from_record(record.reload)
+          end
+        rescue ActiveRecord::RecordNotUnique => e
+          handle_unique_conflict(e, fingerprint)
+        end
+
+        def insert_address_backed(attrs, fingerprint)
+          record = Endpoint.new(
+            user_id: @owner_user_id,
+            channel_key: @channel_key,
+            lifecycle_state: "active",
+            verification_state: "unverified",
+            **attrs,
+          )
+          record.derive_uniqueness_columns!
+          record.save!
+          SafeView.from_record(record)
+        rescue ActiveRecord::RecordNotUnique => e
+          handle_unique_conflict(e, fingerprint)
+        end
+
+        def handle_unique_conflict(error, fingerprint)
+          message = error.message.to_s
+          if message.include?("active_fingerprint")
+            existing = Persistence.find_active_by_fingerprint(
+              owner_user_id: @owner_user_id,
+              channel_key: @channel_key,
+              fingerprint:,
+            )
+            if existing
+              return SafeView.from_record(existing) unless Endpoint.typed_credentials_channel?(@channel_key)
+
+              validated = Validators.validate_pushover_credentials!(@credentials)
+              return resolve_idempotent_pushover(existing, validated)
+            end
+          end
+
+          if message.include?("single_active_slot")
+            raise ConflictError,
+                  "an active endpoint already exists for this owner and channel; use replace"
+          end
+
+          raise ConflictError, "endpoint uniqueness conflict"
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class Error < CommandTower::Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/fingerprinter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      # HMAC fingerprint of Normalized Address. Uses a distinct derived key from SecretBox.
+      module Fingerprinter
+        module_function
+
+        HMAC_PURPOSE = "command_tower.messaging.endpoints.fingerprint.v1"
+
+        def fingerprint(normalized_address)
+          digest = OpenSSL::HMAC.hexdigest("SHA256", derived_hmac_key, normalized_address.to_s)
+          digest
+        end
+
+        def derived_hmac_key
+          OpenSSL::HMAC.digest("SHA256", root_secret, HMAC_PURPOSE)
+        end
+        private_class_method :derived_hmac_key
+
+        def root_secret
+          configured = ENV["COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET"].to_s
+          if configured.empty?
+            if production_like?
+              raise SecretBox::MissingSecretError,
+                    "COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET is required in production"
+            end
+            return "test-messaging-endpoint-secret-not-for-production"
+          end
+
+          configured
+        end
+        private_class_method :root_secret
+
+        def production_like?
+          env = if defined?(Rails) && Rails.respond_to?(:env)
+            Rails.env
+          else
+            ENV["RAILS_ENV"] || ENV["RACK_ENV"]
+          end
+          env.to_s == "production"
+        end
+        private_class_method :production_like?
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/invalid_transition_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class InvalidTransitionError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/lifecycle.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Lifecycle
+        module_function
+
+        TRANSITIONS = {
+          "active" => %w[revoked invalid retired].freeze,
+          "revoked" => %w[retired].freeze,
+          "invalid" => %w[retired].freeze,
+          "retired" => [].freeze,
+        }.freeze
+
+        def assert_transition!(from:, to:)
+          allowed = TRANSITIONS.fetch(from.to_s) { [] }
+          return if allowed.include?(to.to_s)
+
+          raise InvalidTransitionError,
+                "illegal lifecycle transition: #{from.inspect} → #{to.inspect}"
+        end
+
+        def apply!(record, to:, revoked_at: nil)
+          from = record.lifecycle_state
+          assert_transition!(from:, to:)
+          record.lifecycle_state = to.to_s
+          if to.to_s == "revoked"
+            record.revoked_at = revoked_at || Time.current
+          end
+          record.derive_uniqueness_columns!
+          record
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/mark_invalid.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class MarkInvalid
+        def self.call(owner_user_id:, endpoint_id:)
+          new(owner_user_id:, endpoint_id:).call
+        end
+
+        def initialize(owner_user_id:, endpoint_id:)
+          @owner_user_id = owner_user_id
+          @endpoint_id = endpoint_id
+        end
+
+        def call
+          record = Endpoint.for_owner(@owner_user_id).lock.find_by(id: @endpoint_id)
+          raise NotFoundError, "endpoint not found" if record.nil?
+
+          ChannelGate.assert_record_supported!(record)
+
+          return SafeView.from_record(record) if record.lifecycle_state == "invalid"
+          return SafeView.from_record(record) if record.lifecycle_state == "retired"
+
+          Lifecycle.apply!(record, to: "invalid")
+          record.save!
+          SafeView.from_record(record)
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/mark_verification_failed.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class MarkVerificationFailed
+        def self.call(owner_user_id:, endpoint_id:)
+          VerificationTransition.call(owner_user_id:, endpoint_id:, to: "failed")
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/mark_verified.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class MarkVerified
+        def self.call(owner_user_id:, endpoint_id:)
+          VerificationTransition.call(owner_user_id:, endpoint_id:, to: "verified")
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/not_found_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class NotFoundError < Error; end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/persistence.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Persistence
+        module_function
+
+        MAX_RETRIES = 3
+
+        def with_unique_conflict_handling
+          attempts = 0
+          begin
+            attempts += 1
+            yield
+          rescue ActiveRecord::RecordNotUnique => e
+            translated = translate_unique_conflict(e)
+            raise translated if translated
+
+            raise ConflictError, "endpoint uniqueness conflict" if attempts >= MAX_RETRIES
+
+            retry
+          end
+        end
+
+        def translate_unique_conflict(error)
+          message = error.message.to_s
+          if message.include?("index_messaging_endpoints_active_fingerprint") ||
+              message.include?("active_fingerprint")
+            :duplicate_fingerprint
+          elsif message.include?("index_messaging_endpoints_single_active_slot") ||
+              message.include?("single_active_slot")
+            ConflictError.new("an active endpoint already exists for this owner and channel; use replace")
+          else
+            ConflictError.new("endpoint uniqueness conflict")
+          end
+        end
+        private_class_method :translate_unique_conflict
+
+        def find_active_by_fingerprint(owner_user_id:, channel_key:, fingerprint:)
+          Endpoint.active.for_owner(owner_user_id).for_channel(channel_key).find_by(
+            address_fingerprint: fingerprint,
+          )
+        end
+
+        def build_encrypted_attrs(normalized_address:, masked_display_value:)
+          encrypted = SecretBox.encrypt(normalized_address)
+          {
+            address_fingerprint: Fingerprinter.fingerprint(normalized_address),
+            masked_display_value:,
+            address_ciphertext: encrypted.fetch(:ciphertext),
+            encryption_key_version: encrypted.fetch(:key_version),
+          }
+        end
+
+        def build_pushover_parent_attrs(validated:)
+          {
+            address_fingerprint: Fingerprinter.fingerprint(validated.pair_fingerprint_material),
+            masked_display_value: validated.masked_display_value,
+            address_ciphertext: nil,
+            encryption_key_version: SecretBox.key_version,
+          }
+        end
+
+        def build_pushover_credential_attrs(validated:)
+          user_key = SecretBox.encrypt(
+            validated.normalized_user_key,
+            purpose: SecretBox::PUSHOVER_USER_KEY_PURPOSE,
+          )
+          application_token = SecretBox.encrypt(
+            validated.normalized_application_token,
+            purpose: SecretBox::PUSHOVER_APPLICATION_TOKEN_PURPOSE,
+          )
+
+          {
+            user_key_ciphertext: user_key.fetch(:ciphertext),
+            application_token_ciphertext: application_token.fetch(:ciphertext),
+            encryption_key_version: user_key.fetch(:key_version),
+          }
+        end
+
+        def create_pushover_credential!(endpoint:, validated:)
+          ::CommandTower::Messaging::EndpointPushoverCredential.create!(
+            endpoint:,
+            **build_pushover_credential_attrs(validated:),
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/pushover/verify.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Pushover
+        # Single verification authority for Pushover endpoints.
+        # begin → decrypt → validate.json → test messages.json → mark_verified | mark_verification_failed
+        class Verify
+          def self.call(owner_user_id:, endpoint_id:)
+            new(owner_user_id:, endpoint_id:).call
+          end
+
+          def initialize(owner_user_id:, endpoint_id:)
+            @owner_user_id = owner_user_id
+            @endpoint_id = endpoint_id
+          end
+
+          def call
+            record = load_active_pushover!
+            assert_adapter_enabled!
+
+            begin_verification_lifecycle!(record)
+            credentials = SecretReader.read_pushover_credentials!(
+              owner_user_id: @owner_user_id,
+              endpoint_id: @endpoint_id,
+            )
+
+            validate_result = Messaging::Pushover::Transport.validate_user!(
+              user_key: credentials.fetch(:user_key),
+              application_token: credentials.fetch(:application_token),
+            )
+            unless validate_result.success?
+              raise_after_failed!(validate_result)
+            end
+
+            config = CommandTower.config.messaging.pushover
+            test_result = Messaging::Pushover::Transport.send_test_notification!(
+              user_key: credentials.fetch(:user_key),
+              application_token: credentials.fetch(:application_token),
+              title: config.test_title,
+              message: config.test_message,
+            )
+            unless test_result.success?
+              raise_after_failed!(test_result)
+            end
+
+            MarkVerified.call(owner_user_id: @owner_user_id, endpoint_id: @endpoint_id)
+          end
+
+          private
+
+          def load_active_pushover!
+            record = Endpoint.for_owner(@owner_user_id).find_by(id: @endpoint_id)
+            raise NotFoundError, "endpoint not found" if record.nil?
+
+            ChannelGate.assert_record_supported!(record)
+            unless record.channel_key == "pushover"
+              raise ValidationError, "endpoint is not a pushover endpoint"
+            end
+            unless record.active?
+              raise ValidationError, "endpoint must be active to verify"
+            end
+            if record.pushover_credential.nil?
+              raise ValidationError, "pushover credentials are missing"
+            end
+
+            record
+          end
+
+          def assert_adapter_enabled!
+            adapter = CommandTower.config.messaging.pushover.adapter.to_s
+            return unless adapter == "disabled" || adapter.blank?
+
+            raise ValidationError, "Pushover verification adapter is disabled"
+          end
+
+          def begin_verification_lifecycle!(record)
+            case record.verification_state
+            when "pending"
+              nil
+            when "verified"
+              ResetVerification.call(owner_user_id: @owner_user_id, endpoint_id: @endpoint_id)
+              BeginVerification.call(owner_user_id: @owner_user_id, endpoint_id: @endpoint_id)
+            else
+              BeginVerification.call(owner_user_id: @owner_user_id, endpoint_id: @endpoint_id)
+            end
+          end
+
+          def raise_after_failed!(result)
+            MarkVerificationFailed.call(owner_user_id: @owner_user_id, endpoint_id: @endpoint_id)
+            raise VerificationFailedError.new(
+              error_code: result.error_code || :verification_failed,
+              message: result.error_message.presence || "Pushover verification failed",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/endpoints/query.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class Query
+        def self.list(owner_user_id:, channel_key: nil)
+          if channel_key
+            ChannelGate.assert_endpoint_backed!(channel_key)
+          end
+
+          scope = Endpoint.for_owner(owner_user_id).order(:id)
+          scope = scope.where(channel_key: ChannelGate.supported_channel_keys)
+          scope = scope.for_channel(channel_key) if channel_key
+          scope.map { |record| SafeView.from_record(record) }
+        end
+
+        def self.show(owner_user_id:, endpoint_id:)
+          record = Endpoint.for_owner(owner_user_id).find_by(id: endpoint_id)
+          raise NotFoundError, "endpoint not found" if record.nil?
+
+          ChannelGate.assert_record_supported!(record)
+          SafeView.from_record(record)
+        end
+      end
+    end
+  end
+end