command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      # Local retire+insert only. New row is always unverified; never contacts providers.
+      class Replace
+        def self.call(owner_user_id:, channel_key: nil, endpoint_id: nil, address: nil, credentials: nil)
+          new(owner_user_id:, channel_key:, endpoint_id:, address:, credentials:).call
+        end
+
+        def initialize(owner_user_id:, channel_key:, endpoint_id:, address:, credentials:)
+          @owner_user_id = owner_user_id
+          @address = address
+          @credentials = credentials
+          @channel_key = channel_key&.to_s
+          @endpoint_id = endpoint_id
+        end
+
+        def call
+          if @endpoint_id
+            replace_by_endpoint_id
+          elsif @channel_key
+            replace_single_active_channel
+          else
+            raise ValidationError, "replace requires endpoint_id (push) or channel_key (pushover)"
+          end
+        end
+
+        private
+
+        def replace_by_endpoint_id
+          attempts = 0
+          begin
+            attempts += 1
+            Endpoint.transaction do
+              target = Endpoint.for_owner(@owner_user_id).lock.find_by(id: @endpoint_id)
+              raise NotFoundError, "endpoint not found" if target.nil?
+
+              ChannelGate.assert_record_supported!(target)
+              channel_key = target.channel_key
+
+              if Endpoint.typed_credentials_channel?(channel_key)
+                raise ValidationError,
+                      "pushover replace requires channel_key: (single-active), not endpoint_id:"
+              end
+
+              assert_address_only_contract!
+              validated = Validators.validate!(channel_key:, address: @address)
+              attrs = Persistence.build_encrypted_attrs(
+                normalized_address: validated.normalized_address,
+                masked_display_value: validated.masked_display_value,
+              )
+
+              retire!(target)
+              insert_address_replacement(channel_key:, attrs:)
+            end
+          rescue ActiveRecord::RecordNotUnique
+            raise ConflictError, "concurrent endpoint replace conflict" if attempts >= Persistence::MAX_RETRIES
+
+            retry
+          end
+        end
+
+        def replace_single_active_channel
+          ChannelGate.assert_endpoint_backed!(@channel_key)
+          unless Endpoint.single_active_channel?(@channel_key)
+            raise ValidationError,
+                  "channel #{@channel_key.inspect} is multi-active; replace requires endpoint_id"
+          end
+
+          if Endpoint.typed_credentials_channel?(@channel_key)
+            replace_pushover
+          else
+            replace_address_single_active
+          end
+        end
+
+        def replace_pushover
+          assert_pushover_credentials_contract!
+          validated = Validators.validate_pushover_credentials!(@credentials)
+          attrs = Persistence.build_pushover_parent_attrs(validated:)
+
+          attempts = 0
+          begin
+            attempts += 1
+            Endpoint.transaction do
+              retire_actives!(@channel_key)
+              insert_pushover_replacement(attrs:, validated:)
+            end
+          rescue ActiveRecord::RecordNotUnique
+            raise ConflictError, "concurrent endpoint replace conflict" if attempts >= Persistence::MAX_RETRIES
+
+            retry
+          end
+        end
+
+        def replace_address_single_active
+          assert_address_only_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,
+          )
+
+          attempts = 0
+          begin
+            attempts += 1
+            Endpoint.transaction do
+              retire_actives!(@channel_key)
+              insert_address_replacement(channel_key: @channel_key, attrs:)
+            end
+          rescue ActiveRecord::RecordNotUnique
+            raise ConflictError, "concurrent endpoint replace conflict" if attempts >= Persistence::MAX_RETRIES
+
+            retry
+          end
+        end
+
+        def assert_pushover_credentials_contract!
+          if @address.present?
+            raise ValidationError, "pushover replace requires credentials: and must not pass address:"
+          end
+          if @credentials.nil?
+            raise ValidationError, "pushover replace requires credentials: with user_key and application_token"
+          end
+        end
+
+        def assert_address_only_contract!
+          if @credentials.present?
+            raise ValidationError, "channel does not accept credentials:"
+          end
+          if @address.nil?
+            raise ValidationError, "address must be present"
+          end
+        end
+
+        def retire!(target)
+          return if target.terminal?
+
+          Lifecycle.apply!(target, to: "retired")
+          target.save!
+        end
+
+        def retire_actives!(channel_key)
+          Endpoint.active.for_owner(@owner_user_id).for_channel(channel_key).lock.to_a.each do |prior|
+            Lifecycle.apply!(prior, to: "retired")
+            prior.save!
+          end
+        end
+
+        def insert_address_replacement(channel_key:, attrs:)
+          record = Endpoint.new(
+            user_id: @owner_user_id,
+            channel_key:,
+            lifecycle_state: "active",
+            verification_state: "unverified",
+            **attrs,
+          )
+          record.derive_uniqueness_columns!
+          record.save!
+          SafeView.from_record(record)
+        end
+
+        def insert_pushover_replacement(attrs:, validated:)
+          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
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class Revoke
+        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).find_by(id: @endpoint_id)
+          raise NotFoundError, "endpoint not found" if record.nil?
+
+          ChannelGate.assert_record_supported!(record)
+
+          case record.lifecycle_state
+          when "revoked", "retired"
+            return SafeView.from_record(record)
+          when "invalid"
+            Lifecycle.apply!(record, to: "retired")
+            record.save!
+            return SafeView.from_record(record)
+          when "active"
+            Lifecycle.apply!(record, to: "revoked")
+            record.save!
+            SafeView.from_record(record)
+          else
+            raise InvalidTransitionError, "cannot revoke from #{record.lifecycle_state.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      SafeView = Data.define(
+        :id,
+        :owner_user_id,
+        :channel_key,
+        :lifecycle_state,
+        :verification_state,
+        :masked_display_value,
+        :credentials_configured,
+        :encryption_key_version,
+        :verified_at,
+        :revoked_at,
+        :last_successful_use_at,
+        :created_at,
+        :updated_at,
+      ) do
+        def self.from_record(record)
+          new(
+            id: record.id,
+            owner_user_id: record.user_id,
+            channel_key: record.channel_key,
+            lifecycle_state: record.lifecycle_state,
+            verification_state: record.verification_state,
+            masked_display_value: record.masked_display_value,
+            credentials_configured: credentials_configured?(record),
+            encryption_key_version: record.encryption_key_version,
+            verified_at: record.verified_at,
+            revoked_at: record.revoked_at,
+            last_successful_use_at: record.last_successful_use_at,
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+          ).freeze
+        end
+
+        def self.credentials_configured?(record)
+          if record.typed_credentials_channel?
+            record.pushover_credential.present?
+          else
+            record.address_ciphertext.present?
+          end
+        end
+        private_class_method :credentials_configured?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      # Encrypts endpoint secrets at rest using ActiveSupport::MessageEncryptor.
+      # Root secret → separately derived encryption keys per purpose (never shared with Fingerprinter).
+      class SecretBox
+        CURRENT_KEY_VERSION = 1
+        ENCRYPT_PURPOSE = "command_tower.messaging.endpoints.encrypt.v1"
+        PUSHOVER_USER_KEY_PURPOSE = "command_tower.messaging.endpoints.encrypt.pushover.user_key.v1"
+        PUSHOVER_APPLICATION_TOKEN_PURPOSE =
+          "command_tower.messaging.endpoints.encrypt.pushover.application_token.v1"
+        CIPHER = "aes-256-gcm"
+
+        class MissingSecretError < Error; end
+
+        def self.encrypt(plaintext, purpose: ENCRYPT_PURPOSE)
+          new(purpose:).encrypt(plaintext)
+        end
+
+        def self.decrypt(ciphertext, key_version: CURRENT_KEY_VERSION, purpose: ENCRYPT_PURPOSE)
+          new(purpose:).decrypt(ciphertext, key_version:)
+        end
+
+        def self.key_version
+          CURRENT_KEY_VERSION
+        end
+
+        def initialize(purpose: ENCRYPT_PURPOSE)
+          @purpose = purpose.to_s
+        end
+
+        def encrypt(plaintext)
+          payload = encryptor.encrypt_and_sign(plaintext.to_s)
+          { ciphertext: payload, key_version: CURRENT_KEY_VERSION }
+        end
+
+        def decrypt(ciphertext, key_version: CURRENT_KEY_VERSION)
+          raise ValidationError, "unsupported encryption_key_version: #{key_version}" unless key_version.to_i == CURRENT_KEY_VERSION
+
+          encryptor.decrypt_and_verify(ciphertext.to_s)
+        end
+
+        private
+
+        def encryptor
+          @encryptor ||= ActiveSupport::MessageEncryptor.new(
+            derived_encryption_key,
+            cipher: CIPHER,
+            serializer: JSON,
+          )
+        end
+
+        def derived_encryption_key
+          OpenSSL::HMAC.digest("SHA256", root_secret, @purpose)
+        end
+
+        def root_secret
+          configured = ENV["COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET"].to_s
+          if configured.empty?
+            if production_like?
+              raise MissingSecretError,
+                    "COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET is required in production"
+            end
+            return "test-messaging-endpoint-secret-not-for-production"
+          end
+
+          configured
+        end
+
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      # Internal decrypt-at-use. Not part of the safe public façade.
+      class SecretReader
+        def self.read!(owner_user_id:, endpoint_id:)
+          new(owner_user_id:, endpoint_id:).read!
+        end
+
+        def self.read_pushover_credentials!(owner_user_id:, endpoint_id:)
+          new(owner_user_id:, endpoint_id:).read_pushover_credentials!
+        end
+
+        def initialize(owner_user_id:, endpoint_id:)
+          @owner_user_id = owner_user_id
+          @endpoint_id = endpoint_id
+        end
+
+        def read!
+          record = load_supported_record!
+          if record.typed_credentials_channel?
+            raise ValidationError, "use read_pushover_credentials! for pushover endpoints"
+          end
+          if record.address_ciphertext.blank?
+            raise ValidationError, "endpoint has no address ciphertext"
+          end
+
+          SecretBox.decrypt(
+            record.address_ciphertext,
+            key_version: record.encryption_key_version,
+          )
+        end
+
+        def read_pushover_credentials!
+          record = load_supported_record!
+          unless record.channel_key == "pushover"
+            raise ValidationError, "endpoint is not a pushover endpoint"
+          end
+
+          credential = record.pushover_credential
+          raise ValidationError, "pushover credentials are missing" if credential.nil?
+
+          key_version = credential.encryption_key_version
+          {
+            user_key: SecretBox.decrypt(
+              credential.user_key_ciphertext,
+              key_version:,
+              purpose: SecretBox::PUSHOVER_USER_KEY_PURPOSE,
+            ),
+            application_token: SecretBox.decrypt(
+              credential.application_token_ciphertext,
+              key_version:,
+              purpose: SecretBox::PUSHOVER_APPLICATION_TOKEN_PURPOSE,
+            ),
+          }
+        end
+
+        private
+
+        def load_supported_record!
+          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)
+          record
+        end
+      end
+    end
+  end
+end

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

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

data/app/services/command_tower/messaging/endpoints/validators/push.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Validators
+        module Push
+          module_function
+
+          def validate!(address)
+            token = address.to_s.strip
+            raise ValidationError, "push token must be present" if token.empty?
+            raise ValidationError, "push token is too short" if token.length < 8
+
+            Result.new(
+              normalized_address: token,
+              masked_display_value: "Device registered",
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Validators
+        module Pushover
+          module_function
+
+          MIN_LENGTH = 8
+
+          # Legacy single-address path retained for model/spec helpers that still
+          # normalize a user key string — façade create/replace use credentials.
+          def validate!(address)
+            key = normalize_secret!(address, label: "pushover user key")
+            Result.new(
+              normalized_address: key,
+              masked_display_value: mask_user_key(key),
+            )
+          end
+
+          def validate_credentials!(credentials)
+            hash = coerce_credentials!(credentials)
+            user_key = normalize_secret!(hash[:user_key], label: "pushover user key")
+            application_token = normalize_secret!(
+              hash[:application_token],
+              label: "pushover application token",
+            )
+
+            PushoverCredentialsResult.new(
+              normalized_user_key: user_key,
+              normalized_application_token: application_token,
+              masked_display_value: mask_user_key(user_key),
+              pair_fingerprint_material: "#{user_key}\n#{application_token}",
+            )
+          end
+
+          def normalize_secret!(value, label:)
+            secret = value.to_s.strip
+            raise ValidationError, "#{label} must be present" if secret.empty?
+            raise ValidationError, "#{label} is too short" if secret.length < MIN_LENGTH
+
+            secret
+          end
+
+          def mask_user_key(key)
+            if key.length >= 4
+              "#{"•" * 8}#{key[-4, 4]}"
+            else
+              "configured"
+            end
+          end
+
+          def coerce_credentials!(credentials)
+            unless credentials.is_a?(Hash)
+              raise ValidationError, "pushover credentials must be a Hash with user_key and application_token"
+            end
+
+            {
+              user_key: credentials[:user_key] || credentials["user_key"],
+              application_token: credentials[:application_token] || credentials["application_token"],
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Validators
+        Result = Data.define(:normalized_address, :masked_display_value)
+        PushoverCredentialsResult = Data.define(
+          :normalized_user_key,
+          :normalized_application_token,
+          :masked_display_value,
+          :pair_fingerprint_material,
+        )
+
+        module_function
+
+        def for(channel_key)
+          case channel_key.to_s
+          when "push" then Push
+          when "pushover" then Pushover
+          else
+            raise ValidationError, "no validator for channel: #{channel_key.inspect}"
+          end
+        end
+
+        def validate!(channel_key:, address:)
+          self.for(channel_key).validate!(address)
+        end
+
+        def validate_pushover_credentials!(credentials)
+          Pushover.validate_credentials!(credentials)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      module Verification
+        module_function
+
+        TRANSITIONS = {
+          "unverified" => %w[pending verified failed].freeze,
+          "pending" => %w[verified failed unverified].freeze,
+          "verified" => %w[unverified failed].freeze,
+          "failed" => %w[pending unverified].freeze,
+        }.freeze
+
+        def assert_transition!(from:, to:)
+          allowed = TRANSITIONS.fetch(from.to_s) { [] }
+          return if allowed.include?(to.to_s)
+
+          raise InvalidTransitionError,
+                "illegal verification transition: #{from.inspect} → #{to.inspect}"
+        end
+
+        def apply!(record, to:)
+          from = record.verification_state
+          assert_transition!(from:, to:)
+          record.verification_state = to.to_s
+          case to.to_s
+          when "verified"
+            record.verified_at = Time.current
+          when "unverified"
+            record.verified_at = nil
+          end
+          record
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      # Raised after mark_verification_failed when the provider rejected validate/test.
+      # Carries a safe error_code for host mapping; never includes secrets or raw provider bodies.
+      class VerificationFailedError < Error
+        attr_reader :error_code
+
+        def initialize(error_code:, message: "Pushover verification failed")
+          @error_code = error_code.to_sym
+          super(message)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Endpoints
+      class VerificationTransition
+        def self.call(owner_user_id:, endpoint_id:, to:)
+          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)
+
+          Verification.apply!(record, to:)
+          record.save!
+          SafeView.from_record(record)
+        end
+      end
+    end
+  end
+end