spree_cm_commissioner 2.13.3 → 2.13.4

data/app/models/spree_cm_commissioner/mini_app_provider/base.rb

@@ -0,0 +1,219 @@
+require 'ipaddr'
+
+module SpreeCmCommissioner
+  module MiniAppProvider
+    # One class per mini app, the way a payment gateway is one class per provider: the
+    # class declares what that mini app is configured with, and the application's
+    # `provider` names it the way a payment method's `type` names its gateway.
+    #
+    # Preferences are stored in the application's `settings`, under a key of the
+    # mini app's own, so two mini apps can never collide and one mini app's whole
+    # configuration can be read or dropped as a single value.
+    class Base
+      include Spree::Preferences::Preferable
+
+      # Every mini app is throttled the same way, by MiniAppProvider::SessionThrottle; a
+      # mini app shows them by naming this in #preference_groups. Set one to 0 to turn that
+      # cap off.
+      RATE_LIMITS = %i[max_sessions_per_ip max_sessions_per_phone max_new_users].freeze
+
+      preference :max_sessions_per_ip, :integer, default: 600
+      preference :max_sessions_per_phone, :integer, default: 10
+      preference :max_new_users, :integer, default: 100
+
+      # Which addresses a mini app's own servers may call from, for the ones that
+      # call us server to server — see MiniAppProvider::IpRules for what the lists
+      # accept. A mini app shows them by naming this in #preference_groups.
+      IP_RULES = %i[allowed_ips blocked_ips].freeze
+
+      preference :allowed_ips, :string, default: ''
+      preference :blocked_ips, :string, default: ''
+
+      # Who put the current key in place, when, and whether they typed it or we minted it.
+      # Replacing the key overwrites all three; superseded keys survive in the application's
+      # PaperTrail versions.
+      preference :api_key_created_by, :string, default: ''
+      preference :api_key_created_at, :string, default: ''
+      preference :api_key_source, :string, default: ''
+
+      # SecureRandom.hex renders one byte as two characters. Every key is minted here, so any other
+      # length is a truncated paste — it would look right in the field and fail every call after.
+      API_KEY_BYTES = 32
+      API_KEY_LENGTH = 64
+
+      class << self
+        # Registered mini apps, the equivalent of Spree::PaymentMethod.providers.
+        def providers
+          [AcledaBank, WingBank, VattanacBank]
+        end
+
+        # Matches UserIdentityProvider#identity_type, so the mini app that authenticates a
+        # customer and the identity row it writes name the same one. Those enum values
+        # end in `_bank`, which is why these class names do — not every mini app has to
+        # be one.
+        def provider
+          name.demodulize.underscore
+        end
+
+        def for(application)
+          klass = providers.find { |provider_class| provider_class.provider == application.provider.to_s }
+
+          klass&.new(application)
+        end
+
+        # Preferences grouped for the admin form. A mini app with none is configured from
+        # the environment rather than from a row.
+        def preference_groups
+          {}
+        end
+
+        # The preference this mini app cannot be used without. Clearing it revokes the
+        # mini app, and one with none is not run from an application at all.
+        def credential
+          nil
+        end
+
+        # Whether this mini app names itself with an API key on the way in. Only one we take
+        # server-to-server calls from has a request of its own to put a header on — a mini app
+        # whose WebView the partner merely opens arrives as the customer's browser, and the admin
+        # is offered no key it would have nowhere to send.
+        def supports_api_key?
+          false
+        end
+      end
+
+      attr_reader :application
+
+      delegate :id, :uid, to: :application
+      delegate :provider, :preference_groups, :credential, :supports_api_key?, to: :class
+
+      def initialize(application)
+        @application = application
+      end
+
+      # `ip` is Rails' request.remote_ip, so this is only as trustworthy as the proxy
+      # configuration in front of it.
+      #
+      # An address we cannot read is denied whenever an allow list is set: a mini app that named
+      # its addresses is asking us to refuse anything it cannot vouch for. Blocked wins over
+      # allowed.
+      def ip_allowed?(ip)
+        address = to_address(ip)
+
+        return false if address.nil? && allowed_ip_rules.any?
+        return true if address.nil?
+        return false if blocked_ip_rules.any? { |range| range.include?(address) }
+
+        allowed_ip_rules.empty? || allowed_ip_rules.any? { |range| range.include?(address) }
+      end
+
+      # Which address lists do not parse, for the validation that refuses to save them.
+      def invalid_ip_rules
+        IP_RULES.reject { |name| IpRules.valid?(public_send("preferred_#{name}")) }
+      end
+
+      # The header a mini app names itself with, and what an inbound call is looked up by — hence a
+      # column on the application rather than a key in `settings`, where nothing could index it or
+      # keep it unique. A handle, not a credential: #credential is what proves the call.
+      delegate :api_key, to: :application
+
+      # Mints a key, or takes `value` as the key when one is given — the way back from a Generate
+      # pressed by mistake, which no amount of history can undo on its own: the versions say which
+      # keys existed, never which one the partner is holding. Writes in memory like any other
+      # setter, so persisting is the caller's job.
+      def replace_api_key!(value = nil, actor: nil, source: nil)
+        typed = value.to_s.strip
+
+        application.api_key = typed.presence || SecureRandom.hex(API_KEY_BYTES)
+        self.preferred_api_key_source = source || 'generated'
+        self.preferred_api_key_created_by = actor&.id.to_s
+        self.preferred_api_key_created_at = Time.current.iso8601
+
+        api_key
+      end
+
+      # Leaves the mini app with no way in until a new key is generated — the answer to a leak,
+      # where replacing the key would hand the partner a working one they never asked for. The stamp
+      # goes with it: provenance for a key that is gone reads as though one were still in place. The
+      # revoked key survives in the application's PaperTrail versions.
+      def revoke_api_key!
+        application.api_key = nil
+        self.preferred_api_key_source = ''
+        self.preferred_api_key_created_by = ''
+        self.preferred_api_key_created_at = ''
+
+        nil
+      end
+
+      # What the form shows in place of the key, which it never renders after the one dialog that
+      # follows minting. The last four characters are what the partner can read back over the phone, and
+      # four of sixty-four hex characters give away nothing that matters.
+      def masked_api_key
+        return nil if api_key.blank?
+
+        "#{'•' * 20}#{api_key.last(4)}"
+      end
+
+      # The caption the admin form renders under the key — one sentence, so one method rather
+      # than three readers the view has to reassemble. Each half degrades on its own: the admin
+      # who generated the key may be gone, and `settings` is hand-editable JSON, so the stamp may
+      # not parse. Neither may cost us the fact that someone did put this key in place.
+      def api_key_provenance
+        return nil if api_key.blank?
+
+        action = preferred_api_key_source == 'restored' ? 'Restored' : 'Generated'
+
+        "#{action} #{api_key_created_at_phrase} by #{api_key_author}"
+      end
+
+      # Preferable reads and writes this in place, so it must be one hash for the life of
+      # the instance; #preferences_will_change! is what puts it back on the record. The
+      # defaults are merged in so the admin form can render every field of a mini app
+      # that has never been saved, the way Spree::Base seeds a payment method's column.
+      def preferences
+        @preferences ||= default_preferences.with_indifferent_access.merge(stored_preferences)
+      end
+
+      def preferences_will_change!
+        application.settings = application.settings.merge(provider => preferences.to_h)
+      end
+
+      private
+
+      def allowed_ip_rules
+        @allowed_ip_rules ||= IpRules.parse(preferred_allowed_ips)
+      end
+
+      def blocked_ip_rules
+        @blocked_ip_rules ||= IpRules.parse(preferred_blocked_ips)
+      end
+
+      def to_address(ip)
+        IPAddr.new(ip.to_s)
+      rescue IPAddr::Error
+        nil
+      end
+
+      def api_key_created_at_phrase
+        time = Time.zone.parse(preferred_api_key_created_at.to_s)
+
+        time ? time.strftime('%d %b %Y %H:%M') : 'at an unknown time'
+      rescue ArgumentError
+        'at an unknown time'
+      end
+
+      # Falls back to the stored id once that admin is gone, rather than losing the fact that
+      # someone did generate it.
+      def api_key_author
+        stored_id = preferred_api_key_created_by
+        return 'unknown' if stored_id.blank?
+
+        Spree.user_class.find_by(id: stored_id)&.email || stored_id
+      end
+
+      def stored_preferences
+        (application.settings[provider] || {}).with_indifferent_access
+      end
+    end
+  end
+end

data/app/models/spree_cm_commissioner/mini_app_provider/vattanac_bank.rb

@@ -0,0 +1,6 @@
+module SpreeCmCommissioner
+  module MiniAppProvider
+    class VattanacBank < Base
+    end
+  end
+end

data/app/models/spree_cm_commissioner/mini_app_provider/wing_bank.rb

@@ -0,0 +1,30 @@
+module SpreeCmCommissioner
+  module MiniAppProvider
+    class WingBank < Base
+      # The mini app pair Wing issues. `app_id` is echoed back in every getProfile
+      # response and `secret_api_key` salts the hash that signs it — see
+      # SpreeCmCommissioner::WingMiniApp::ProfileVerifier for both.
+      preference :app_id, :string, default: ''
+      preference :secret_api_key, :string, default: ''
+
+      # Blank accepts level_1a or above — the lowest level whose hash formula includes
+      # `phone`, which is how a Wing customer is matched to an existing account. Set it
+      # to pin verification to exactly one level: level_0, level_1, level_1a, level_1b,
+      # level_2 or level_3.
+      preference :data_level, :string, default: ''
+
+      def self.credential
+        :secret_api_key
+      end
+
+      def self.preference_groups
+        {
+          credentials: %i[app_id secret_api_key],
+          verification: %i[data_level],
+          ip_rules: IP_RULES,
+          rate_limits: RATE_LIMITS
+        }
+      end
+    end
+  end
+end

data/app/models/spree_cm_commissioner/oauth_application_decorator.rb

@@ -2,6 +2,13 @@ module SpreeCmCommissioner
   module OauthApplicationDecorator
     def self.prepended(base)
       base.belongs_to :tenant, class_name: 'SpreeCmCommissioner::Tenant'
+      base.include SpreeCmCommissioner::OauthApplication::MiniApp
+
+      # The only record of a mini app's past API keys. MiniAppProvider::Base#replace_api_key!
+      # overwrites the key and its stamp in place, so without this a rotation leaves nothing behind to
+      # answer what the old key was, who replaced it, or when. `versions.object` carries the whole
+      # previous row, the mini app's `settings` with it.
+      base.has_paper_trail
 
       # treat a key inside a JSONB column like a normal Rails attribute,
       # with getter/setter methods

data/app/models/spree_cm_commissioner/product_dynamic_field.rb

@@ -6,9 +6,18 @@ module SpreeCmCommissioner
     validates :dynamic_field_id, uniqueness: { scope: :product_id }
 
     after_commit :enqueue_data_fill_stage_maintenance, on: %i[create]
+    after_commit :enqueue_product_cache_invalidation
 
     private
 
+    # Purges the CDN-cached storefront dynamic_fields response for this product. Also covers
+    # DynamicField destroy, which cascades here via dependent: :destroy.
+    def enqueue_product_cache_invalidation
+      SpreeCmCommissioner::MaintenanceTasks::CacheInvalidation
+        .pending
+        .create_or_find_by(maintainable_type: 'Spree::Product', maintainable_id: product_id)
+    end
+
     # Only newly-added fields need active recompute: adding a field can make an
     # already-complete guest newly incomplete, which needs a persisted-column fix and a
     # catch-up notification. Removing a field can only shrink the required set, which

data/app/models/spree_cm_commissioner/user_identity_provider.rb

@@ -1,6 +1,6 @@
 module SpreeCmCommissioner
   class UserIdentityProvider < Base
-    enum identity_type: { :google => 0, :apple => 1, :facebook => 2, :telegram => 3, :vattanac_bank => 4 }
+    enum identity_type: { :google => 0, :apple => 1, :facebook => 2, :telegram => 3, :vattanac_bank => 4, :acleda_bank => 5, :wing_bank => 6 }
 
     belongs_to :user, class_name: Spree.user_class.to_s, optional: false
     has_one :tenant, through: :user

data/app/services/spree_cm_commissioner/mini_app_provider/api_key_history.rb

@@ -0,0 +1,128 @@
+module SpreeCmCommissioner
+  module MiniAppProvider
+    # The keys an application used to hold, newest first, read out of its PaperTrail versions.
+    #
+    # A version's `object` is the row *before* that change, so its `api_key` is a key that was current
+    # until then and its `settings` carry that key's own stamp.
+    class ApiKeyHistory
+      Entry = Struct.new(:version_id, :key, :created_at, :created_by, :source, :revoked, keyword_init: true)
+
+      # How many versions to read, not how many keys come back: most versions record a settings change
+      # and carry the key unchanged, so a window of 50 is what it takes to reach the last few keys. It
+      # has to be bounded at all because this runs on every render of the edit page and versions are
+      # never pruned.
+      LIMIT = 50
+
+      def initialize(application)
+        @application = application
+      end
+
+      # Deduplicated, because saving without touching the key writes the same one into another version,
+      # and the key in use now is left out — restoring it would do nothing.
+      def entries
+        seen = [current_ciphertext].compact
+
+        versions.filter_map do |version|
+          ciphertext = ciphertext_in(version)
+          next if ciphertext.blank? || seen.include?(ciphertext)
+
+          seen << ciphertext
+          entry_for(version, ciphertext)
+        end
+      end
+
+      # The plaintext a version recorded, or nil if that version is gone or no longer decryptable — an
+      # encryption key rotation leaves the ciphertext unreadable, and a caller must not take nil for a
+      # key worth saving.
+      def key_for(version_id)
+        version = versions.find { |candidate| candidate.id.to_s == version_id.to_s }
+        return nil if version.nil?
+
+        decrypt(ciphertext_in(version))
+      end
+
+      private
+
+      attr_reader :application
+
+      def versions
+        @versions ||= application.versions.reorder(id: :desc).limit(LIMIT).to_a
+      end
+
+      def entry_for(version, ciphertext)
+        return nil if decrypt(ciphertext).blank?
+
+        stamp = stamp_in(version)
+
+        Entry.new(
+          version_id: version.id,
+          key: decrypt(ciphertext),
+          created_at: parse_time(stamp['api_key_created_at']),
+          created_by: author(stamp['api_key_created_by']),
+          source: stamp['api_key_source'],
+          revoked: revoked?(version, ciphertext)
+        )
+      end
+
+      # The key this one gave way to. nil there means it was cleared rather than replaced — a revoke,
+      # which is what a leak is answered with, so the list says so rather than offering it silently.
+      def revoked?(version, ciphertext)
+        index = versions.index(version)
+        successor = index.zero? ? current_ciphertext : ciphertext_in(versions[index - 1])
+
+        successor.blank? && ciphertext.present?
+      end
+
+      def attributes_in(version)
+        @attributes_in ||= {}
+        @attributes_in[version.id] ||= YAML.unsafe_load(version.object.to_s) || {}
+      rescue Psych::Exception, ArgumentError
+        {}
+      end
+
+      def ciphertext_in(version)
+        attributes_in(version)['api_key']
+      end
+
+      def stamp_in(version)
+        settings = attributes_in(version)['settings']
+        settings = JSON.parse(settings) if settings.is_a?(String)
+
+        (settings || {})[application.provider.to_s] || {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Raw SQL, because reading the attribute would hand back the decrypted key and there would be
+      # nothing left to compare the versions' ciphertext against.
+      def current_ciphertext
+        @current_ciphertext ||= application.class.connection.select_value(
+          application.class.where(id: application.id).select(:api_key).to_sql
+        )
+      end
+
+      def decrypt(ciphertext)
+        return nil if ciphertext.blank?
+
+        @decrypted ||= {}
+        @decrypted[ciphertext] ||= application.class.type_for_attribute(:api_key).deserialize(ciphertext)
+      rescue StandardError
+        nil
+      end
+
+      # `settings` is hand-editable JSON, so the stamp may not parse. A row with no date still names a
+      # key worth restoring.
+      def parse_time(value)
+        Time.zone.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def author(id)
+        return nil if id.blank?
+
+        Spree.user_class.find_by(id: id)&.email || id
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/mini_app_provider/ip_rules.rb

@@ -0,0 +1,26 @@
+require 'ipaddr'
+
+module SpreeCmCommissioner
+  module MiniAppProvider
+    # Reads a mini app's address list — a free-form set of addresses or CIDR ranges,
+    # `1.2.3.4`, `203.0.113.0/24`, IPv6 alike, separated by commas, spaces or newlines.
+    # MiniAppProvider::Base#ip_allowed? is what matches an address against them.
+    class IpRules
+      def self.parse(value)
+        value.to_s.split(/[,\s]+/).filter_map do |entry|
+          IPAddr.new(entry)
+        rescue IPAddr::Error
+          nil
+        end
+      end
+
+      # True when every entry is a usable address or range, so a typo is caught on save
+      # rather than by locking the mini app out on its next request.
+      def self.valid?(value)
+        entries = value.to_s.split(/[,\s]+/)
+
+        entries.size == parse(value).size
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/mini_app_provider/session_gate.rb

@@ -0,0 +1,79 @@
+module SpreeCmCommissioner
+  module MiniAppProvider
+    # Who is calling, from where, and how often — the three questions every mini app session
+    # asks, answered once so each new mini app inherits them.
+    #
+    # It answers them, it does not sequence them: SessionThrottle has to run after the mini
+    # app's own signature check, so each service keeps its own order. With no application row
+    # nothing is configured, so everything is allowed — the signature is what guards the
+    # endpoint, not this.
+    class SessionGate
+      def initialize(provider:, api_key: nil, ip: nil)
+        @provider = provider.to_s
+        @api_key = api_key
+        @ip = ip
+      end
+
+      # A mini app we take server-to-server calls from must always name itself, so only a key
+      # that finds its row passes. One whose WebView the partner merely opens has no request to
+      # put a header on — the customer's browser arrives — so it sends no key and passes on
+      # provider alone, even before anyone has configured a row for it.
+      def api_key_accepted?
+        return mini_app.present? if key_required?
+
+        true
+      end
+
+      def address_allowed?
+        mini_app.nil? || ip.blank? || mini_app.ip_allowed?(ip)
+      end
+
+      # `phone` must be the normalized intel_phone_number — see SessionThrottle.
+      def session_exceeded?(phone: nil)
+        throttle(phone)&.session_exceeded? || false
+      end
+
+      def new_user_exceeded?(phone: nil)
+        throttle(phone)&.new_user_exceeded? || false
+      end
+
+      # The configured mini app, or nil when none is set up. Carries the credential each
+      # mini app checks its own callers with.
+      #
+      # .mini_app_for takes the key as a required keyword so it can never answer as though a
+      # missing one had been checked, which is why the caller picks the lookup rather than
+      # passing a key that may be nil.
+      def mini_app
+        return @mini_app if defined?(@mini_app)
+
+        @mini_app = if api_key.present?
+                      Spree::OauthApplication.mini_app_for(provider, api_key: api_key)
+                    else
+                      Spree::OauthApplication.keyless_mini_app_for(provider)
+                    end
+      end
+
+      private
+
+      attr_reader :provider, :api_key, :ip
+
+      # Asked of the registry rather than of a row: a call with no key may have no row to ask,
+      # and that is exactly the case this has to answer for.
+      #
+      # Fully qualified — a bare `Base` resolves up the nesting to SpreeCmCommissioner::Base.
+      def key_required?
+        provider_class = SpreeCmCommissioner::MiniAppProvider::Base.providers.find do |klass|
+          klass.provider == provider
+        end
+
+        provider_class&.supports_api_key? || false
+      end
+
+      def throttle(phone)
+        return nil if mini_app.nil?
+
+        SpreeCmCommissioner::MiniAppProvider::SessionThrottle.new(mini_app: mini_app, ip: ip, phone: phone)
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/mini_app_provider/session_throttle.rb

@@ -0,0 +1,66 @@
+module SpreeCmCommissioner
+  module MiniAppProvider
+    # Runs *after* the signature is verified, so a trip here means correctly signed traffic is
+    # flooding us — the signal that a mini app's key leaked — not unsigned internet noise.
+    # Rack::Attack sits in front of Rails and cannot tell those apart, hence not middleware.
+    #
+    # #new_user_exceeded? is the cap that survives IP rotation: minting accounts is the damage
+    # a leaked key actually does, and returning customers never consume that quota.
+    class SessionThrottle
+      WINDOW = 60 # seconds
+
+      # `phone` must be the normalized intel_phone_number, not what the caller sent: keying on
+      # the raw string multiplies an allowance by alternating 012345678 and +85512345678.
+      def initialize(mini_app:, ip:, phone:)
+        @mini_app = mini_app
+        @ip = ip
+        @phone = phone
+      end
+
+      def session_exceeded?
+        (ip.present? && exceeded?(scope: 'ip', key: "ip:#{ip}", limit: mini_app.preferred_max_sessions_per_ip)) ||
+          (phone.present? && exceeded?(scope: 'phone', key: "phone:#{phone}", limit: mini_app.preferred_max_sessions_per_phone))
+      end
+
+      def new_user_exceeded?
+        exceeded?(scope: 'new_user', key: 'new_users', limit: mini_app.preferred_max_new_users)
+      end
+
+      private
+
+      attr_reader :mini_app, :ip, :phone
+
+      def exceeded?(scope:, key:, limit:)
+        namespaced_key = "throttle:mini_app:#{mini_app.provider}:#{mini_app.id}:#{key}"
+
+        result = SpreeCmCommissioner::RequestGuard.with_request_guard do
+          SpreeCmCommissioner::RateLimiter.call(key: namespaced_key, limit: limit, window: WINDOW)
+        end
+
+        # nil means the guard skipped the block for an exempt (load-test) request.
+        return false if result.nil? || !result.exceeded?
+
+        log_throttled(scope, namespaced_key, result)
+        true
+      end
+
+      def log_throttled(scope, key, result)
+        CmAppLogger.error(
+          label: 'Mini app session throttled',
+          data: {
+            scope: scope,
+            key: key,
+            count: result.count,
+            limit: result.limit,
+            window: WINDOW,
+            provider: mini_app.provider,
+            mini_app_id: mini_app.id,
+            client_id: mini_app.uid,
+            ip: ip,
+            phone: phone
+          }
+        )
+      end
+    end
+  end
+end

data/app/services/spree_cm_commissioner/payment_method_type_mapper.rb

@@ -1,7 +1,9 @@
 module SpreeCmCommissioner
   class PaymentMethodTypeMapper
     TYPES = {
-      'vattanac_mini_app' => 'Spree::Gateway::VattanacMiniApp'
+      'vattanac' => 'Spree::Gateway::VattanacMiniApp',
+      'acleda' => 'Spree::Gateway::AcledaMiniApp',
+      'wing' => 'Spree::Gateway::WingMiniApp'
     }.freeze
 
     def self.call(type)

data/app/services/spree_cm_commissioner/rate_limiter/result.rb

@@ -0,0 +1,20 @@
+module SpreeCmCommissioner
+  class RateLimiter
+    # Outcome of one increment: hits seen in the current window, the cap that
+    # applied, and whether this call went over it. A plain class rather than a
+    # Struct so `count` stays a hit count and not Enumerable#count.
+    class Result
+      attr_reader :count, :limit
+
+      def initialize(count:, limit:, exceeded:)
+        @count = count
+        @limit = limit
+        @exceeded = exceeded
+      end
+
+      def exceeded?
+        @exceeded
+      end
+    end
+  end
+end