kiosk-server 0.5.20

data/lib/kiosk/server/events.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The topic registry, shaped like {Queries} and {Actions}. A topic takes
+    # `reach` from the verbs' four values; `subject_reachable` takes the
+    # subject and identity, because it is re-run on a socket with no request.
+    module Events
+      # Declared on every topic, as `output_schema` is on every verb.
+      REQUIRED = %i[description payload_schema].freeze
+
+      class << self
+        # rubocop:disable-next Metrics/ParameterLists -- each keyword is one member of the published topic declaration
+        def register(name:, reach:, description:, payload_schema:, subject_reachable:, examples: [])
+          name = name.to_s
+          declaration = { name:, reach:, description:, payload_schema:, examples:, subject_reachable: }.freeze
+
+          # The same declaration again (a reload) is a no-op.
+          return if registry[name] == declaration
+          raise ArgumentError, already_declared(name) if registry.key?(name)
+
+          registry[name] = declaration
+        end
+
+        def unregister(name) = registry.delete(name.to_s)
+
+        def fetch(name) = registry[name.to_s]
+
+        def known = registry.keys.sort
+
+        # Published beside `queries` and `actions`; `subject_reachable` is the operator's rule, not wire.
+        def catalog = known.map { |name| catalog_entry(registry[name]) }
+
+        # Appends one event to the tail of every identity in `identity_scope`. `reach` authorises
+        # subscribing; `identity_scope` names who is told about this transition.
+        # @param identity_scope [Array<String>] user_ids; empty writes nothing
+        # @return [Integer, nil] the id of the last append, nil for an empty scope
+        def emit(topic:, data:, identity_scope:, subject: nil, occurred_at: nil)
+          name = topic.to_s
+          raise ArgumentError, undeclared(name) unless fetch(name)
+
+          event = {
+            'topic' => name,
+            'subject' => subject,
+            'occurred_at' => (occurred_at || Time.current).utc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+            'data' => data
+          }
+          Array(identity_scope).map { |identity_key| append(identity_key, event) }.last
+        end
+
+        def reset! = registry.clear
+
+        private
+
+        def registry = (@registry ||= {})
+
+        def catalog_entry(declaration)
+          entry = { name: declaration[:name], description: declaration[:description],
+                    reach: declaration[:reach].to_s, payload_schema: declaration[:payload_schema] }
+          entry[:examples] = declaration[:examples] if declaration[:examples].any?
+          entry
+        end
+
+        # Append before broadcast, so every pushed id can be resumed from.
+        def append(identity_key, event)
+          id = Kiosk.configuration.event_store.append(identity_key, event)
+          EventsCable.broadcast(identity_key, event.merge('id' => id))
+          id
+        end
+
+        def already_declared(name)
+          "topic #{name.inspect} is already declared on this origin. A topic name is one " \
+            'wire name and one payload shape; declare it once, on the controller that owns ' \
+            'the transition it reports.'
+        end
+
+        def undeclared(name)
+          "#{name.inspect} is not a declared topic on this origin. Declare it with " \
+            "`topic #{name.to_sym.inspect} do … end` on the controller that owns the " \
+            'transition it reports; known topics: ' \
+            "#{known.empty? ? '(none)' : known.join(', ')}."
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/events_cable.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'action_cable'
+require 'json'
+require 'rack'
+
+module Kiosk
+  module Server
+    # The engine's own Action Cable server, so the host's connection class and forgery setting stay
+    # the host's. One stream per (identity, topic); the channel filters by subject.
+    module EventsCable
+      STREAM_PREFIX = 'kiosk:events'
+
+      # A lambda, so the server is built on first request, once the host's
+      # `config/cable.yml` can be read.
+      RACK_APP = ->(env) { Kiosk::Server::EventsCable.serve(env) }
+
+      UNSERVED_DETAIL = 'this operator does not serve the events module'
+      UNSERVED_HINT   = "`events` is absent from this origin's capabilities and it publishes no " \
+                        'events_url; there is nothing to subscribe to here'
+
+      CABLE_YML_MISSING = '[kiosk-server] this origin serves events and has no config/cable.yml. ' \
+                          'Add one with a production adapter that every process shares, ' \
+                          'for example `adapter: solid_cable`.'
+      CABLE_ADAPTER_MISSING = '[kiosk-server] config/cable.yml names no adapter for %<env>s. ' \
+                              'Set one that every process shares, for example `adapter: solid_cable`.'
+
+      class << self
+        # An origin that declares no topic answers `501 module_not_served`
+        # (spec Sections 8.5.3, 16.1 item 9), before any credential is read.
+        def serve(env)
+          return unserved_module if Kiosk::Server::Events.known.empty?
+
+          server.call(env)
+        end
+
+        def server
+          @server ||= ::ActionCable::Server::Base.new(config: configuration)
+        end
+
+        def stream_name(identity_key, topic)
+          "#{STREAM_PREFIX}:#{identity_key}:#{topic}"
+        end
+
+        # Called by {Events.emit} after the append, so the event carries its id.
+        def broadcast(identity_key, event)
+          server.broadcast(stream_name(identity_key, event['topic']), event)
+        end
+
+        # The host's `config/cable.yml`. Outside production a host without one gets
+        # `async`, which serves one process only. In production this raises.
+        def cable_config
+          return host_cable_config if rails_app_with_cable_yml?
+          raise Errors::ConfigurationError, CABLE_YML_MISSING if production?
+
+          { 'adapter' => 'async' }
+        end
+
+        def configuration
+          @configuration ||= ::ActionCable::Server::Configuration.new.tap do |config|
+            config.connection_class = -> { Kiosk::Server::EventsConnection }
+            config.cable = cable_config
+            config.logger = resolved_logger
+            # Authorised by the `Authorization` header, which a page cannot attach cross-origin.
+            config.disable_request_forgery_protection = true
+          end
+        end
+
+        private
+
+        def unserved_module
+          error   = Errors::ModuleNotServed.new(UNSERVED_DETAIL, hint: UNSERVED_HINT)
+          headers = ::Rack::Headers.new
+          headers['content-type'] = Errors::PROBLEM_CONTENT_TYPE
+          Headers.add_to(headers)
+          Headers.add_cache_policy(headers, status: error.http_status)
+          [error.http_status, headers, [::JSON.generate(error.to_problem)]]
+        end
+
+        def rails_app_with_cable_yml?
+          defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application &&
+            ::Rails.root&.join('config/cable.yml')&.exist?
+        end
+
+        def host_cable_config
+          config = ::Rails.application.config_for(:cable).to_h.transform_keys(&:to_s)
+          return config if config['adapter']
+
+          raise Errors::ConfigurationError, format(CABLE_ADAPTER_MISSING, env: ::Rails.env)
+        end
+
+        def production? = defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.production?
+
+        def resolved_logger
+          return ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+          ::Logger.new(IO::NULL)
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/events_connection.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'action_cable'
+require 'json'
+require 'rack'
+
+module Kiosk
+  module Server
+    # The Action Cable connection behind `<endpoint>/events`, authenticated from the
+    # `Authorization` header, never the query string, which access logs record.
+    class EventsConnection < ::ActionCable::Connection::Base
+      # A String: Action Cable serialises every `identified_by` value.
+      identified_by :kiosk_identity_key
+
+      attr_reader :kiosk_identity
+
+      # Action Cable beats every 3 seconds; forwarding one in ten keeps a client from drowning in them.
+      BEATS_PER_PING = 10
+
+      # The one channel a frame here may name; see {KioskEvents}.
+      CHANNEL = 'KioskEvents'
+
+      # A subscriber never publishes (spec Section 8.5.5), so no `message`.
+      COMMANDS = %w[subscribe unsubscribe].freeze
+
+      # §8.5.6: the credential is re-checked at least every 60 seconds, on every socket.
+      class_attribute :reauthorise_every, default: 30
+
+      # The `subscribe` identifiers that the upgrade URL's `topic` and `since` declare.
+      module UrlSubscriptions
+        module_function
+
+        def identifiers(query_string)
+          query = ::Rack::Utils.parse_query(query_string)
+          since = since(query['since'])
+          topics(query['topic']).map do |topic, subject|
+            identifier = { 'channel' => CHANNEL, 'topic' => topic }
+            identifier['subject'] = subject if subject
+            identifier['since'] = since if since
+            ::JSON.generate(identifier)
+          end
+        end
+
+        # `?topic=todo&topic=delivery` or `?topic=todo,delivery`, a subject after
+        # a colon (a topic name cannot hold one). `Rack::Utils.parse_query`
+        # because Rails keeps only the last of a repeated key.
+        def topics(raw)
+          Array(raw).flat_map { |value| value.to_s.split(',') }
+                    .map(&:strip).reject(&:empty?)
+                    .map { |value| value.split(':', 2) }
+                    .map { |topic, subject| [topic, (subject unless subject.to_s.empty?)] }
+        end
+
+        # Digits become an Integer; anything else passes through for
+        # {KioskEvents} to refuse.
+        def since(value)
+          value = value.last if value.is_a?(Array)
+          return nil if value.blank?
+
+          value.match?(/\A\d+\z/) ? value.to_i : value
+        end
+      end
+
+      def connect
+        identity = resolve_identity || reject_unauthorized_connection
+        @kiosk_identity = identity
+        self.kiosk_identity_key = identity.user_id.to_s
+      end
+
+      # Subscriptions declared in the URL (§8.5.4) become `subscribe` commands.
+      def handle_open
+        super
+        return unless @kiosk_identity
+
+        @reauthorisation = server.event_loop.timer(reauthorise_every) { send_async(:reauthorise!) }
+        auto_subscribe!
+      end
+
+      def handle_close
+        @reauthorisation&.shutdown
+        super
+      end
+
+      def beat
+        @beats = (@beats || 0) + 1
+        super if (@beats % BEATS_PER_PING).zero?
+      end
+
+      # Every frame is answered (§8.5.4, §8.5.7); a repeated `subscribe` is confirmed again, not replayed.
+      def dispatch_websocket_message(websocket_message)
+        frame = parse_object(websocket_message) || {}
+        command = frame['command']
+        identifier = frame['identifier']
+
+        return close_invalid_request unless COMMANDS.include?(command) && identifier.is_a?(::String)
+
+        live = subscriptions.identifiers.include?(identifier)
+        return transmit_about(identifier, :confirmation) if command == 'subscribe' && live
+        return transmit_about(identifier, :rejection) unless actionable?(command, identifier, live)
+
+        super
+      end
+
+      # Closes with `token_expired` or `revoked` once the credential no longer resolves (§8.5.6).
+      def kiosk_credential_holds?
+        return true if resolve_identity
+
+        if kiosk_credential_expired?
+          close(reason: 'token_expired', reconnect: true)
+        else
+          close(reason: 'revoked', reconnect: false)
+        end
+        false
+      end
+
+      private
+
+      def reauthorise!
+        kiosk_credential_holds?
+      rescue StandardError => e
+        logger.error("[kiosk] events re-authorisation failed: #{e.class}: #{e.message}")
+      end
+
+      def kiosk_credential_expired?
+        exp = kiosk_identity.claims&.dig(:exp)
+        !exp.nil? && Time.now.to_i >= exp.to_i
+      end
+
+      # Nil for anything that is not a JSON object.
+      def parse_object(document)
+        parsed = ::JSON.parse(document)
+        parsed if parsed.is_a?(::Hash)
+      rescue ::JSON::ParserError
+        nil
+      end
+
+      def close_invalid_request
+        close(reason: ::ActionCable::INTERNAL[:disconnect_reasons][:invalid_request], reconnect: false)
+      end
+
+      def transmit_about(identifier, type)
+        transmit(identifier: identifier, type: ::ActionCable::INTERNAL[:message_types][type])
+      end
+
+      # An `unsubscribe` must name a live subscription by its exact string; a
+      # `subscribe` must name this channel, and {KioskEvents} judges the rest.
+      def actionable?(command, identifier, live)
+        return live if command == 'unsubscribe'
+
+        parse_object(identifier)&.dig('channel') == CHANNEL
+      end
+
+      def auto_subscribe!
+        UrlSubscriptions.identifiers(request.query_string).each do |identifier|
+          subscriptions.execute_command('command' => 'subscribe', 'identifier' => identifier)
+        end
+      end
+
+      # Under the upgrade's own issuer: this runs outside {IssuerMiddleware}.
+      # A raising IdP refuses the upgrade rather than failing the socket.
+      def resolve_identity
+        issuer = Kiosk.configuration.issuer_for(request.base_url)
+        Kiosk.with_issuer(issuer) { Kiosk::Server::IdentityResolution.resolve(request) }
+      rescue StandardError => e
+        logger&.error("[kiosk] events connection identity resolution failed: #{e.class}")
+        nil
+      end
+    end
+  end
+end

data/lib/kiosk/server/executor/repeat.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    class Executor
+      # A `pay` whose chain was presented before (§11.6).
+      module Repeat
+        private
+
+        # A chain presented before. Settled: its settlement. Neither settled nor
+        # declined: the chain, to capture again. Anything else is a conflict.
+        def repeat(chain)
+          row = recorded_chain(chain)
+          raise Errors::Conflict.new('mandate already processed', hint: Pay::CONFLICT_HINT) if row.nil? || row['declined_at']
+          return stored_settlement(row) if row['settlement_id']
+
+          chain.cart_row = row.fetch('cart_row')
+          chain.repeat   = true
+          chain
+        end
+
+        def recorded_chain(chain)
+          return nil if chain.intent.nil? || chain.cart.nil? || chain.payment.nil?
+
+          row = nil
+          SessionContext.open(connection: connection, identity: identity) { row = chain_record(chain) }
+          row
+        end
+
+        def stored_settlement(row)
+          settlement_result(row.fetch('settlement_id'), row.fetch('psp_reference'),
+                            row.fetch('settled_amount_cents').to_i, row.fetch('currency'))
+        end
+
+        # A refusal under which no money moved: the cart stops counting against the spending cap.
+        def decline(chain)
+          SessionContext.open(connection: connection, identity: identity) { decline_cart(chain.cart_row) }
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/executor/spending_cap.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    class Executor
+      # The assistant's spending cap, checked at pay time.
+      module SpendingCap
+        private
+
+        # A nil seam or a nil cap means uncapped. A cap allows no payment in
+        # another currency. Runs in the transaction that persists the cart,
+        # under a per-assistant lock, so two concurrent pays see each other: the
+        # second counts the first's cart as in flight. A cart already recorded
+        # is a repeat and adds nothing.
+        def enforce_spending_cap!(cart)
+          cap = Kiosk.configuration.spending_cap&.call(agent_id: identity.agent_id)
+          return if cap.nil? # this assistant is uncapped
+
+          lock_assistant_payments!(identity.agent_id)
+          return if cart_recorded?(cart)
+
+          refuse_other_currency!(cap.fetch(:currency), cart)
+          refuse_over_cap!(cap.fetch(:amount_cents).to_i, cart)
+        end
+
+        def refuse_other_currency!(cap_currency, cart)
+          cap_code = MandateVerifier.canonical_currency(cap_currency)
+          cart_code = MandateVerifier.canonical_currency(cart.currency)
+          return if cap_code == cart_code
+
+          raise Errors::SpendingCapExceeded.new('assistant spending cap is in another currency',
+                                                hint: "the cap is in #{cap_code.upcase}; this charge is in #{cart_code.upcase}")
+        end
+
+        def refuse_over_cap!(cap, cart)
+          window_days = Kiosk.configuration.spending_cap_window_days
+          spent = spent_in_window(cart, window_days)
+          return if spent + cart.total_amount_cents.to_i <= cap
+
+          raise Errors::SpendingCapExceeded.new('assistant spending cap exceeded', hint: cap_hint(cap, spent, window_days, cart))
+        end
+
+        # One tally per currency: cents are not fungible across currencies. One
+        # statement, so a settlement committed between two reads is counted once.
+        def spent_in_window(cart, window_days)
+          binds = spent_binds(identity.agent_id, cart.currency, window_days)
+          sql = "SELECT (#{settled_sql(window_days)}) + (#{in_flight_sql}) AS total"
+          connection.exec_query(sql, 'Kiosk spent total', binds).to_a.first.fetch('total').to_i
+        end
+
+        def cap_hint(cap, spent, window_days, cart)
+          window_note = window_days ? " in the last #{window_days.to_i} day(s)" : ''
+          "cap #{cap} cents; #{spent} already settled or in flight#{window_note}; " \
+            "this charge is #{cart.total_amount_cents.to_i}"
+        end
+
+        # Settled cents for this agent in one currency (see SettledSpend),
+        # case-folded on both sides so `eur` and `EUR` are one tally. No window
+        # means no predicate; the day count is a bind.
+        def settled_sql(window_days)
+          schema = Kiosk.configuration.schema
+          window = window_days ? 'AND settled_at >= now() - make_interval(days => $3)' : ''
+          <<~SQL.squish
+            SELECT COALESCE(SUM(#{SettledSpend.net_cents_sql(schema)}), 0) AS total
+            FROM #{schema}.settlements
+            WHERE agent_id = $1 AND lower(btrim(currency)) = $2 #{window}
+          SQL
+        end
+
+        # Carts of this agent whose mandate is live, that have no settlement and
+        # were not declined: a capture may still run for each.
+        def in_flight_sql
+          schema = Kiosk.configuration.schema
+          <<~SQL.squish
+            SELECT COALESCE(SUM(c.total_amount_cents), 0) AS total
+            FROM #{schema}.cart_mandates c
+            WHERE c.agent_id = $1 AND lower(btrim(c.currency)) = $2 AND c.expires_at > now()
+              AND c.declined_at IS NULL
+              AND NOT EXISTS (SELECT 1 FROM #{schema}.settlements s WHERE s.cart_mandate_id = c.id)
+          SQL
+        end
+
+        # The agent, the canonical currency and, with a window, its day count.
+        def spent_binds(agent_id, currency, window_days)
+          binds = [agent_id, MandateVerifier.canonical_currency(currency)]
+          window_days ? binds << window_days.to_i : binds
+        end
+
+        def cart_recorded?(cart)
+          sql = "SELECT 1 FROM #{Kiosk.configuration.schema}.cart_mandates WHERE user_id = $1 AND mandate_id = $2"
+          connection.exec_query(sql, 'Kiosk cart recorded', [cart.user_id, cart.id]).any?
+        end
+
+        # Held to the end of the transaction; an advisory lock needs no grant on any table.
+        def lock_assistant_payments!(agent_id)
+          connection.exec_query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))',
+                                'Kiosk spending cap lock', [agent_id.to_s])
+        end
+      end
+    end
+  end
+end