kiosk-test-support 0.5.20

data/lib/kiosk/test_helpers/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module TestHelpers
+    # Errors this gem raises, from the journey DSL and the conformance checks.
+    module Errors
+      class RLSDenied < StandardError; end
+
+      # No shipped executor raises this yet; `NullExecutor` can.
+      class QuotaExceeded < StandardError; end
+
+      class ExecutorNotConfigured < StandardError
+        DEFAULT_MESSAGE = <<~MSG.strip
+          Kiosk::TestHelpers has no executor configured.
+
+          Wire one in your test helper:
+
+            # spec/spec_helper.rb or test/test_helper.rb
+            require "kiosk/test_helpers/in_process_executor"
+            Kiosk::TestHelpers.executor = Kiosk::TestHelpers::InProcessExecutor.new
+
+          For unit-shaped tests, use the bundled NullExecutor:
+
+            Kiosk::TestHelpers.executor = Kiosk::TestHelpers::NullExecutor.new
+        MSG
+
+        def initialize(message = DEFAULT_MESSAGE)
+          super
+        end
+      end
+
+      class OriginNotConfigured < StandardError
+        DEFAULT_MESSAGE = <<~MSG.strip
+          Kiosk::TestHelpers::Conformance has no origin configured.
+
+          Wire one in your test helper:
+
+            # spec/spec_helper.rb or test/test_helper.rb
+            require "kiosk/test_helpers/conformance/in_process_origin"
+            Kiosk::TestHelpers::Conformance.origin = Kiosk::TestHelpers::Conformance::InProcessOrigin.new
+
+          For unit-shaped tests with no Rails and no database, use the bundled
+          NullOrigin:
+
+            Kiosk::TestHelpers::Conformance.origin =
+              Kiosk::TestHelpers::Conformance::NullOrigin.new
+        MSG
+
+        def initialize(message = DEFAULT_MESSAGE)
+          super
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/in_process_executor.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# Needs kiosk-server, which only a Rails host carries; this gem does not depend
+# on it, so a test helper requires this file explicitly:
+#   require "kiosk/test_helpers/in_process_executor"
+#   Kiosk::TestHelpers.executor = Kiosk::TestHelpers::InProcessExecutor.new
+
+require 'date'
+require 'kiosk/server'
+require 'kiosk/test_helpers/errors'
+require 'kiosk/test_helpers/in_process_wire'
+
+module Kiosk
+  module TestHelpers
+    # Runs the kiosk-test-support journey DSL against a real connection: each
+    # identity scope sets the GUCs and always rolls back, and an RLS denial
+    # surfaces as {Kiosk::TestHelpers::Errors::RLSDenied}. A verb goes through
+    # its route, as an assistant calls it.
+    class InProcessExecutor
+      class NoScopeError < StandardError; end
+
+      # Aborts the transaction, also on a connection double that ignores `ActiveRecord::Rollback`.
+      class RollbackMarker < StandardError; end
+
+      attr_reader :connection, :system_connection, :current_identity
+
+      # `system_connection` seeds irrespective of RLS; it defaults to `connection`.
+      # `app` is the Rack app a verb call goes through; it defaults to `Rails.application`.
+      def initialize(connection: nil, system_connection: nil, app: nil)
+        @connection        = connection        || default_connection
+        @system_connection = system_connection || @connection
+        @wire              = InProcessWire.new(app: app)
+        @current_identity  = nil
+        @scope_depth       = 0
+      end
+
+      def in_scope? = @scope_depth.positive?
+
+      def with_identity(identity, &block)
+        # Before touching scope state, so a rescued blockless call leaves it intact.
+        raise ArgumentError, 'block required' unless block
+
+        previous_identity = @current_identity
+        @current_identity = identity
+        @scope_depth     += 1
+        begin
+          call_rolled_back(identity, block)
+        ensure
+          @current_identity = previous_identity
+          @scope_depth     -= 1
+        end
+      end
+
+      def query(sql)
+        require_scope!
+        rescue_rls_denials do
+          Sql.rows(connection.execute(sql))
+        end
+      end
+
+      # A paginated answer returns its rows, as the caller receives them.
+      def run_query(name, args) = call_verb(name, :query, args)
+
+      def run_action(name, args) = call_verb(name, :action, args)
+
+      # Settlement captures against a PSP, which an always-rolled-back scope cannot host.
+      def pay_action(_name, _args)
+        require_scope!
+        raise NotImplementedError, 'pay is not exercised through the RLS journey DSL; ' \
+                                   'settlement runs via Executor#verb_pay + a kiosk-pay-* provider'
+      end
+
+      def seed(table, attrs, count:)
+        count.times.map do
+          Sql.rows(system_connection.execute(Sql.insert(table, attrs))).first
+        end
+      end
+
+      private
+
+      def default_connection = ::ActiveRecord::Base.lease_connection
+
+      # A refusal coded `rls_denied` surfaces as {Kiosk::TestHelpers::Errors::RLSDenied}.
+      def call_verb(name, kind, args)
+        require_scope!
+        @wire.call(name, kind: kind, params: args, identity: current_identity)
+      rescue Kiosk::Server::Errors::WireError => e
+        raise Kiosk::TestHelpers::Errors::RLSDenied, e.message if e.code == 'rls_denied'
+
+        raise
+      end
+
+      def require_scope!
+        return if in_scope?
+
+        raise NoScopeError,
+              'call from inside as_user / as_agent / as_anonymous block (default-deny)'
+      end
+
+      # The block's result, or its error re-raised, after the transaction always rolls back.
+      def call_rolled_back(identity, block)
+        result = caught = nil
+        rolled_back do
+          apply_gucs(identity) if identity
+          result, caught = capture { block.call(self) }
+        end
+        raise caught if caught
+
+        result
+      end
+
+      def rolled_back
+        connection.transaction do
+          yield
+          raise RollbackMarker
+        end
+      rescue RollbackMarker
+        # The rollback is the point; the marker stops here.
+      end
+
+      def capture
+        [yield, nil]
+      rescue StandardError => e
+        [nil, e]
+      end
+
+      def apply_gucs(identity)
+        Kiosk::Server::SessionContext.new(connection: connection, identity: identity)
+                                     .guc_statements
+                                     .each { |sql, binds| connection.exec_query(sql, 'Kiosk GUC', binds) }
+      end
+
+      def rescue_rls_denials
+        yield
+      rescue StandardError => e
+        raise Kiosk::TestHelpers::Errors::RLSDenied, e.message if Sql.rls_denial?(e)
+
+        raise
+      end
+
+      # SQL literals, result rows, and the errors Postgres raises for an RLS denial.
+      module Sql
+        module_function
+
+        def insert(table, attrs)
+          cols       = attrs.keys
+          values_sql = cols.map { |c| quote_value(attrs[c]) }.join(', ')
+          col_sql    = cols.map { |c| quote_ident(c.to_s) }.join(', ')
+          %(INSERT INTO #{quote_ident(table.to_s)} (#{col_sql}) ) +
+            %(VALUES (#{values_sql}) RETURNING *)
+        end
+
+        # Result rows with symbol keys.
+        def rows(result)
+          return [] if result.nil?
+
+          Array(result).map do |row|
+            row.respond_to?(:transform_keys) ? row.transform_keys(&:to_sym) : row
+          end
+        end
+
+        def rls_denial?(error)
+          return true if rls_message?(error.message)
+
+          cause = error.respond_to?(:cause) ? error.cause : nil
+          cause && rls_message?(cause.message)
+        end
+
+        def rls_message?(message)
+          return false if message.nil?
+
+          message = message.to_s
+          message.include?('row-level security') ||
+            message.include?('violates row-level') ||
+            message.include?('permission denied for table')
+        end
+
+        def quote_value(value)
+          case value
+          when nil                  then 'NULL'
+          when true                 then 'TRUE'
+          when false                then 'FALSE'
+          when Numeric              then value.to_s
+          # `getutc`: `Time#utc` mutates and `DateTime#utc` needs ActiveSupport.
+          when Time, DateTime       then "'#{value.to_time.getutc.iso8601}'"
+          when Date                 then "'#{value.iso8601}'"
+          else
+            "'#{value.to_s.gsub("'", "''")}'"
+          end
+        end
+
+        def quote_ident(name)
+          name.to_s.split('.').map { |part| %("#{part.gsub('"', '""')}") }.join('.')
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/in_process_wire.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Needs kiosk-server, which only a Rails host carries; this gem does not depend
+# on it, so a test helper requires this file explicitly.
+
+require 'json'
+require 'openssl'
+require 'rack/mock'
+require 'uri'
+require 'kiosk/server'
+require 'kiosk/test_helpers/wire'
+
+module Kiosk
+  module TestHelpers
+    # Calls a verb of the booted app through its route, in this process, as an
+    # assistant does: one linked to the principal's account, as a person links
+    # one, and paying any proof-of-work toll. A caller with no identity sends no
+    # token.
+    class InProcessWire
+      # `app` defaults to the Rails application, middleware included.
+      def initialize(app: nil)
+        @app = app
+      end
+
+      # The verb's answer, or the wire error its refusal names.
+      def call(name, kind:, params:, identity:)
+        token      = token_for(identity) if identity
+        response   = request(name, kind, params, token)
+        challenges = toll_challenges(response)
+        response   = request(name, kind, params, token, Wire.solve(challenges)) if challenges
+        answer(response)
+      end
+
+      private
+
+      def app = @app || ::Rails.application
+
+      def request(name, kind, params, token, proofs = nil)
+        env = credentials(token, proofs)
+        url = "#{Kiosk.current_issuer.to_s.chomp('/')}#{Kiosk.configuration.mount_path}/#{name}"
+        return Rack::MockRequest.new(app).get(query_url(url, params), env) if kind.to_sym == :query
+
+        Rack::MockRequest.new(app).post(url, env.merge(input: JSON.generate(params), 'CONTENT_TYPE' => 'application/json'))
+      end
+
+      def credentials(token, proofs)
+        { 'HTTP_AUTHORIZATION' => ("Bearer #{token}" if token),
+          'HTTP_KIOSK_POW' => (JSON.generate(proofs) if proofs) }.compact
+      end
+
+      def query_url(url, params) = params.empty? ? url : "#{url}?#{URI.encode_www_form(params)}"
+
+      # The token of an assistant linked to the principal for this call.
+      def token_for(identity)
+        Kiosk::Server::AccountBinding.bind!(
+          public_key_pem: OpenSSL::PKey::RSA.generate(2048).public_key.to_pem,
+          user_id: identity.user_id, requested_role: identity.role
+        ).fetch(:access_token)
+      end
+
+      def toll_challenges(response)
+        problem = parse(response.body)
+        return unless response.status == 402 && problem.is_a?(Hash) && problem['code'] == 'pow_required'
+
+        problem['challenges']
+      end
+
+      def answer(response)
+        body = parse(response.body)
+        return body if response.successful?
+
+        raise refusal(response.status, body)
+      end
+
+      def refusal(status, body)
+        return RuntimeError.new("the origin answered #{status}: #{body.inspect}") unless problem?(body)
+
+        Kiosk::Server::Errors::WireError.new(body['detail'], code: body['code'], hint: body['hint'])
+      end
+
+      def problem?(body) = body.is_a?(Hash) && Kiosk::Server::Errors::CODES.key?(body['code'])
+
+      def parse(raw)
+        raw.to_s.empty? ? nil : JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/journey.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Kiosk
+  module TestHelpers
+    # The journey-test DSL, for RSpec `type: :kiosk_journey` groups and Minitest
+    # cases. The `as_*` scopes take a block and delegate to the executor.
+    module Journey
+      # @param user [#id, #role] the principal; `user.id` becomes `current_user_id`
+      # @param role [String, Symbol, nil] defaults to `user.role`, else the first configured role
+      def as_agent_of(user, role: nil, &)
+        identity = Kiosk::Identity.new(
+          user_id: user_id_of(user),
+          role: resolve_role(user, role),
+          actor: 'agent',
+          agent_id: SecureRandom.uuid
+        )
+        scope_to(identity, &)
+      end
+
+      def as_user(user, role: nil, &)
+        identity = Kiosk::Identity.new(
+          user_id: user_id_of(user),
+          role: resolve_role(user, role),
+          actor: 'human'
+        )
+        scope_to(identity, &)
+      end
+
+      # An agent for a synthetic user named `name`, when no `users` row exists.
+      def as_agent(name, role: nil, &)
+        identity = Kiosk::Identity.new(
+          user_id: "synthetic:#{name}",
+          role: role&.to_s || default_role,
+          actor: 'agent',
+          agent_id: SecureRandom.uuid
+        )
+        scope_to(identity, &)
+      end
+
+      def as_anonymous(&)
+        scope_to(nil, &)
+      end
+
+      # Raw SQL; a query verb is {#run_query}.
+      def query(sql)
+        TestHelpers.require_executor!.query(sql)
+      end
+
+      def run_query(name, **args)
+        TestHelpers.require_executor!.run_query(name, args)
+      end
+
+      def run_action(name, **args)
+        TestHelpers.require_executor!.run_action(name, args)
+      end
+
+      # `Kiosk::TestHelpers::InProcessExecutor` raises `NotImplementedError` here.
+      def pay_action(name, **args)
+        TestHelpers.require_executor!.pay_action(name, args)
+      end
+
+      # Runs as `system_role`, so it can seed RLS tables; `owner:` sets `user_id`.
+      def kiosk_seed(table, count: 1, owner: nil, **attrs)
+        attrs = attrs.merge(user_id: user_id_of(owner)) if owner
+        TestHelpers.require_executor!.seed(table, attrs, count: count)
+      end
+
+      private
+
+      def scope_to(identity, &block)
+        raise ArgumentError, 'block required' unless block
+
+        TestHelpers.require_executor!.with_identity(identity, &block)
+      end
+
+      def user_id_of(user)
+        user.respond_to?(:id) ? user.id : user
+      end
+
+      def resolve_role(user, explicit)
+        return explicit.to_s if explicit
+
+        if user.respond_to?(:role) && user.role
+          user.role.to_s
+        else
+          default_role
+        end
+      end
+
+      def default_role
+        roles = Kiosk.configuration.roles
+        roles.first.to_s if roles && !roles.empty?
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/kyc.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'openssl'
+require 'securerandom'
+require 'uri'
+require 'kiosk'
+require 'kiosk/test_helpers/wire'
+
+module Kiosk
+  module TestHelpers
+    # Stands in for the operator's KYC provider for the length of each test, so
+    # the test decides how an identity check ends.
+    #
+    #   include Kiosk::TestHelpers::Kyc
+    #
+    #   rider.requests_verification
+    #   the_verification_service_confirms(rider, age_over_18: true)
+    module Kyc
+      ISSUER   = 'https://kyc.test.invalid'
+      SETTINGS = %i[kyc_provider kyc_issuer kyc_public_key].freeze
+
+      # Opens checks without a network and signs attestations for them.
+      class Provider < Kiosk::KycProviders::Base
+        Check = Data.define(:subject, :audience, :nonce, :callback_url)
+
+        def self.key = @key ||= OpenSSL::PKey::RSA.generate(2048)
+
+        def initialize
+          super
+          @checks = {}
+        end
+
+        def open_verification(subject:, audience:, callback_url:, **)
+          request_id = SecureRandom.uuid
+          @checks[request_id] = Check.new(subject:, audience:, nonce: SecureRandom.hex(16), callback_url:)
+          { request_id:, nonce: @checks[request_id].nonce, verification_url: "#{ISSUER}/verify?request=#{request_id}" }
+        end
+
+        def latest_check_for(subject)
+          @checks.select { |_, check| check.subject == subject.to_s }.keys.last or
+            raise ArgumentError, "no check was opened for #{subject.inspect}"
+        end
+
+        def check(request_id) = @checks.fetch(request_id)
+
+        def attest(subject, audience, attributes)
+          now = Time.now.to_i
+          JWT.encode({ sub: subject.to_s, level: 'verified', iss: ISSUER, aud: audience.to_s, attributes:,
+                       iat: now, exp: now + 3600 }, self.class.key, 'RS256')
+        end
+      end
+
+      def self.included(base)
+        before, after = base.respond_to?(:setup) ? %i[setup teardown] : %i[before after]
+        base.public_send(before) { stand_in_for_kyc_provider }
+        base.public_send(after) { restore_kyc_provider }
+      end
+
+      # The person behind `customer` passed the check they asked for last, with
+      # these attributes; the provider reports so through the callback the engine gave it.
+      def the_verification_service_confirms(customer, **attributes)
+        request_id = @kyc_provider.latest_check_for(customer.principal.user_id)
+        check  = @kyc_provider.check(request_id)
+        jws    = @kyc_provider.attest(check.subject, check.audience, attributes)
+        answer = deliver_callback(check, { request_id:, nonce: check.nonce, kyc_jws: jws })
+        raise "the engine refused the KYC callback: #{answer.status} #{answer.body}" unless answer.status == 200
+
+        jws
+      end
+
+      # An attestation the provider signed for this principal, as an assistant
+      # submits it to `POST <endpoint>/agents/kyc`.
+      def kyc_attestation(principal, **attributes)
+        @kyc_provider.attest(principal.user_id, Kiosk.configuration.kyc_audience, attributes)
+      end
+
+      private
+
+      def deliver_callback(check, body)
+        Wire.new(base_url: URI.join(check.callback_url, '/').to_s).post(URI(check.callback_url).path, body)
+      end
+
+      def stand_in_for_kyc_provider
+        config = Kiosk.configuration
+        @replaced_kyc_settings = SETTINGS.to_h { [it, config.public_send(it)] }
+        @kyc_provider = Provider.new
+        config.kyc_provider   = @kyc_provider
+        config.kyc_issuer     = ISSUER
+        config.kyc_public_key = Provider.key.public_key
+      end
+
+      def restore_kyc_provider
+        @replaced_kyc_settings&.each { |setting, value| Kiosk.configuration.public_send(:"#{setting}=", value) }
+      end
+    end
+  end
+end

data/lib/kiosk/test_helpers/live_server.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'puma'
+require 'socket'
+require 'kiosk/test_helpers/assistant'
+
+module Kiosk
+  module TestHelpers
+    # Tests whose writes must be committed: each starts from the seeds and
+    # leaves the database empty.
+    module SeededDatabase
+      def self.included(base)
+        base.use_transactional_tests = false
+        base.setup do
+          SeededDatabase.empty
+          Rails.application.load_seed
+        end
+        base.teardown { SeededDatabase.empty }
+      end
+
+      def self.empty
+        connection = ActiveRecord::Base.connection
+        schemas = ActiveRecord.dump_schemas.split(',').map { connection.quote(it.strip) }.join(', ')
+        tables = connection.select_values(<<~SQL)
+          SELECT format('%I.%I', schemaname, tablename) FROM pg_tables
+          WHERE schemaname IN (#{schemas}) AND tablename NOT IN ('schema_migrations', 'ar_internal_metadata')
+        SQL
+        connection.execute("TRUNCATE #{tables.join(', ')} RESTART IDENTITY CASCADE") if tables.any?
+      end
+    end
+
+    # Serves the app over HTTP from the test process, on a free port that
+    # becomes the origin's issuer, so a test drives the wire as an assistant does.
+    module LiveServer
+      def self.included(base)
+        base.include SeededDatabase
+      end
+
+      def self.url
+        @url ||= begin
+          port   = TCPServer.open('127.0.0.1', 0) { |socket| socket.addr[1] }
+          server = Puma::Server.new(Rails.application, nil, min_threads: 0, max_threads: 8)
+          server.add_tcp_listener('127.0.0.1', port)
+          server.run
+          Kiosk.configuration.issuer = "http://127.0.0.1:#{port}"
+        end
+      end
+
+      def live_url = LiveServer.url
+
+      def assistant = @assistant ||= Assistant.new(base_url: live_url)
+
+      def register = assistant.register!
+    end
+  end
+end

data/lib/kiosk/test_helpers/null_executor.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module TestHelpers
+    # In-memory executor that records every call without touching Postgres; the
+    # contract `Kiosk::TestHelpers::InProcessExecutor` implements. Queue results with
+    # `enqueue_<kind>` and errors with `enqueue_error`.
+    class NullExecutor
+      Call = Data.define(:kind, :args, :identity)
+
+      attr_reader :calls
+
+      def initialize
+        @calls          = []
+        @identity_stack = []
+        @queues         = Hash.new { |h, k| h[k] = [] }
+        @errors         = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def with_identity(identity)
+        @identity_stack.push(identity)
+        yield
+      ensure
+        @identity_stack.pop
+      end
+
+      def query(sql)
+        record(:query, { sql: sql })
+        next_result_or_raise(:query)
+      end
+
+      def run_query(name, args)
+        record(:run_query, { name: name, args: args })
+        next_result_or_raise(:run_query)
+      end
+
+      def run_action(name, args)
+        record(:run_action, { name: name, args: args })
+        next_result_or_raise(:run_action)
+      end
+
+      def pay_action(name, args)
+        record(:pay_action, { name: name, args: args })
+        next_result_or_raise(:pay_action)
+      end
+
+      def seed(table, attrs, count:)
+        record(:seed, { table: table, attrs: attrs, count: count })
+        next_result_or_raise(:seed)
+      end
+
+      def enqueue_query(result)       = @queues[:query]       << result
+      def enqueue_run_query(result)   = @queues[:run_query]   << result
+      def enqueue_run_action(result)  = @queues[:run_action]  << result
+      def enqueue_pay_action(result)  = @queues[:pay_action]  << result
+      def enqueue_seed(result)        = @queues[:seed]        << result
+
+      # `error` is :rls_denied, :quota_exceeded, or a class.
+      def enqueue_error(kind, error = :rls_denied)
+        @errors[kind] << error
+      end
+
+      def calls_of(kind) = @calls.select { |c| c.kind == kind }
+
+      def current_identity = @identity_stack.last
+
+      private
+
+      def record(kind, args)
+        @calls << Call.new(kind: kind, args: args, identity: current_identity)
+      end
+
+      def next_result_or_raise(kind)
+        if (err = @errors[kind].shift)
+          raise resolve_error(err)
+        end
+
+        @queues[kind].empty? ? default_for(kind) : @queues[kind].shift
+      end
+
+      def default_for(kind)
+        %i[query run_query].include?(kind) ? [] : nil
+      end
+
+      def resolve_error(err)
+        case err
+        when :rls_denied      then Errors::RLSDenied
+        when :quota_exceeded  then Errors::QuotaExceeded
+        when Class            then err
+        else raise ArgumentError, "unknown enqueued error #{err.inspect}"
+        end
+      end
+    end
+  end
+end