kiosk-server 0.5.20 → 0.6.28

data/lib/kiosk/server/payment_claim.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
-require 'kiosk/uuid_check'
-
 module Kiosk
   module Server
     # §11.6 over a PSP adapter: claims the operator's payable row `unpaid →
-    # paying` before the capture, checks the cart against the operator's price,
+    # paying` before the capture, checks the checkout against the operator's price,
     # flips the row to `paid` once the capture returns, tells its owner on the
     # `payment` topic, and runs `c.after_payment` once the settlement is recorded.
     # A refund through it is recorded against the settlement.
@@ -19,7 +17,7 @@ module Kiosk
       attr_reader :currency, :reference
 
       # @param model [String] the payable model's name, e.g. "Order"; it includes Kiosk::Owned and Kiosk::Payable
-      # @param reference [String] the cart line-item key naming the row, e.g. "order_id"
+      # @param reference [String] the checkout line-item key naming the row, e.g. "order_id"
       # @param query [String] the per-user query that publishes the row's payment state
       def initialize(psp, currency:, model:, reference:, query:)
         @psp       = psp
@@ -34,12 +32,12 @@ module Kiosk
       # The same claim over another PSP adapter.
       def over(psp) = self.class.new(psp, **@options)
 
-      def capture(cart_mandate, payment_method: nil) = charge_row(claim!(cart_mandate), cart_mandate, payment_method)
+      def capture(checkout_mandate, payment_method: nil) = charge_row(claim!(checkout_mandate), checkout_mandate, payment_method)
 
       delegate :setup_required?, :setup_url, to: :@psp
 
-      # The settlements whose cart names this row.
-      def settlements(id) = Kiosk::Settlement.joins(:cart_mandate).merge(Kiosk::CartMandate.referencing(@reference => id))
+      # The settlements whose checkout names this row.
+      def settlements(id) = Kiosk::Settlement.joins(:checkout_mandate).merge(Kiosk::CheckoutMandate.referencing(@reference => id))
 
       def settled?(id) = settlements(id).exists?
 
@@ -58,15 +56,15 @@ module Kiosk
 
       private
 
-      def charge_row(id, cart_mandate, payment_method)
-        settled = charge(id, cart_mandate, payment_method)
+      def charge_row(id, checkout_mandate, payment_method)
+        settled = charge(id, checkout_mandate, payment_method)
         mark_paid!(id)
         settled
       end
 
       # Releases the claim when the PSP refuses before any money moved.
-      def charge(id, cart_mandate, payment_method)
-        @psp.capture(cart_mandate, payment_method: payment_method)
+      def charge(id, checkout_mandate, payment_method)
+        @psp.capture(checkout_mandate, payment_method: payment_method)
       rescue Kiosk::PaymentProviders::SetupRequired
         release!(id)
         raise
@@ -75,11 +73,11 @@ module Kiosk
         raise
       end
 
-      def claim!(cart)
-        id = referenced_id(cart)
-        refuse_unclaimable!(id, cart.user_id.to_s) unless @row.take(id, cart.user_id.to_s, from: UNPAID, to: PAYING).positive?
+      def claim!(checkout)
+        id = Lines.reference(checkout.line_items, @reference)
+        refuse_unclaimable!(id, checkout.user_id.to_s) unless @row.take(id, checkout.user_id.to_s, from: UNPAID, to: PAYING).positive?
         begin
-          check_price!(cart, id)
+          check_price!(checkout, id)
         rescue StandardError
           release!(id)
           raise
@@ -87,28 +85,20 @@ module Kiosk
         id
       end
 
-      # The one row the cart's line items name, in the operator's currency.
-      def referenced_id(cart)
-        deny "cart currency #{cart.currency.inspect} rejected — this operator prices in #{@currency.upcase}" unless cart.currency.to_s.downcase == @currency
-        Lines.reference(cart.line_items, @reference)
-      end
-
-      def check_price!(cart, id)
-        total = cart.total_amount_cents.to_i
-        lines = Array(cart.line_items).reject { |li| li[@reference] }
-        Lines.check_sum!(total, lines)
-
-        price = checker.call(id, lines)
+      # The price may have moved since the checkout was signed.
+      def check_price!(checkout, id)
+        total = checkout.total_amount_cents
+        price = checker.call(id, checkout.line_items.reject { |li| li[@reference] })
         deny price if price.is_a?(String)
         return if total == price
 
-        deny "cart total #{total} does not equal this operator's price #{price} for #{noun} #{id} — " \
-             'sign the `cart` that the action which created it returned'
+        deny "checkout total #{total} does not equal this operator's price #{price} for #{noun} #{id}: " \
+             'the price changed after the operator signed the checkout'
       end
 
       def checker
-        Kiosk.configuration.cart_price_checker or
-          raise Errors::ConfigurationError, "PaymentClaim needs c.cart_price_checker, the operator's price"
+        Kiosk.configuration.checkout_price_checker or
+          raise Errors::ConfigurationError, "PaymentClaim needs c.checkout_price_checker, the operator's price"
       end
 
       def refuse_unclaimable!(id, payer)
@@ -123,8 +113,8 @@ module Kiosk
           mark_paid!(id)
           deny "#{noun} #{id} is already paid"
         end
-        deny "#{noun} #{id} has a payment in progress under another chain. Send that chain again, " \
-             'byte for byte: it cannot charge twice. Do not sign a new chain. ' \
+        deny "#{noun} #{id} has a payment in progress under other mandates. Send those mandates again, " \
+             'byte for byte: they cannot charge twice. Do not sign new mandates. ' \
              "GET <endpoint>/#{@query} shows the payment state."
       end
 
@@ -134,62 +124,41 @@ module Kiosk
         raise Errors::Forbidden, message
       end
 
-      # The cart's line items: the one row they name, and the priced lines' sum.
+      # The checkout's line items: the one row they name.
       module Lines
         module_function
 
         def reference(line_items, key)
-          refs = Array(line_items).filter_map { |li| li[key] }.map(&:to_s).uniq
-          deny "cart line_items must reference exactly one #{key}" unless refs.size == 1
-          id = refs.first
-          return id if Kiosk::UuidCheck.valid?(id)
-
-          raise Errors::BadRequest.new("cart line_items #{key} #{id.inspect} is not a uuid",
-                                       hint: "use the `#{key}` this operator returned, verbatim")
-        end
-
-        # The priced lines, when any, sum to the cart total.
-        def check_sum!(total, lines)
-          priced = lines.select { |li| li['price_cents'] }
-          return if priced.empty?
-
-          sum = priced.sum do |li|
-            qty = li['qty'].to_i
-            price = li['price_cents'].to_i
-            deny 'each priced line needs a positive qty and price_cents' if qty <= 0 || price <= 0
-            qty * price
-          end
-          deny "cart total #{total} does not equal the sum of its line items #{sum}" unless total == sum
-        end
+          refs = line_items.filter_map { |li| li[key] }.uniq
+          return refs.first.to_s if refs.one?
 
-        def deny(message)
-          raise Errors::Forbidden, message
+          raise Errors::Forbidden, "checkout line_items must name exactly one #{key}"
         end
       end
 
-      # A repeat of a chain whose capture did not complete. The row stays with
-      # the newest unfinished chain, and the PSP keys the capture by the cart
-      # mandate id, so the repeat cannot charge twice.
+      # A repeat of mandates whose capture did not complete. The row stays with
+      # the newest unfinished checkout mandate, and the PSP keys the capture by
+      # its reference, so the repeat cannot charge twice.
       module Resume
-        def resume(cart_mandate, payment_method: nil) = charge_row(reclaim!(cart_mandate), cart_mandate, payment_method)
+        def resume(checkout_mandate, payment_method: nil) = charge_row(reclaim!(checkout_mandate), checkout_mandate, payment_method)
 
         private
 
-        # The row this repeated chain claimed, or the row it may claim now.
-        def reclaim!(cart)
-          id = referenced_id(cart)
-          payer = cart.user_id.to_s
+        # The row these repeated mandates claimed, or the row they may claim now.
+        def reclaim!(checkout)
+          id = Lines.reference(checkout.line_items, @reference)
+          payer = checkout.user_id.to_s
           status = @row.status(id, payer)
-          return claim!(cart) if status == UNPAID
-          return id if [PAYING, PAID].include?(status) && !settled?(id) && unfinished_chain(id, payer) == cart.id
+          return claim!(checkout) if status == UNPAID
+          return id if [PAYING, PAID].include?(status) && !settled?(id) && unfinished_mandate(id, payer) == checkout.reference
 
           refuse_unclaimable!(id, payer)
         end
 
-        # The signed id of the newest cart for this row that is neither settled nor declined.
-        def unfinished_chain(id, payer)
-          Kiosk::CartMandate.referencing(@reference => id).where(user_id: payer, declined_at: nil)
-                            .where.missing(:settlements).order(created_at: :desc, id: :desc).pick(:mandate_id)
+        # The reference of the newest checkout mandate for this row that is neither settled nor declined.
+        def unfinished_mandate(id, payer)
+          Kiosk::CheckoutMandate.referencing(@reference => id).where(user_id: payer, declined_at: nil)
+                                .where.missing(:settlements).order(created_at: :desc, id: :desc).pick(:reference)
         end
       end
       include Resume
@@ -208,8 +177,8 @@ module Kiosk
         end
 
         INSERT_SQL = <<~SQL.squish
-          INSERT INTO "%<schema>s".refunds (settlement_id, psp_reference, refunded_amount_cents, refunded_at)
-          SELECT id, $1, $2, $3 FROM "%<schema>s".settlements WHERE psp_reference = $4
+          INSERT INTO "%<schema>s".kiosk_refunds (settlement_id, psp_reference, refunded_amount_cents, refunded_at)
+          SELECT id, $1, $2, $3 FROM "%<schema>s".kiosk_settlements WHERE psp_reference = $4
           ON CONFLICT (psp_reference) DO NOTHING
         SQL
       end
@@ -218,10 +187,10 @@ module Kiosk
       # The operator's work after a payment, which reads the settlement.
       module AfterPayment
         # The executor calls this once, after it records the settlement of
-        # `cart_mandate`, so `c.after_payment` reads the row's `settlement`. A
-        # failure here never surfaces on the wire: the log carries it.
-        def settled(cart_mandate)
-          id = Lines.reference(cart_mandate.line_items, @reference)
+        # `checkout_mandate`, so `c.after_payment` reads the row's `settlement`. A
+        # failure here never surfaces in the response: the log carries it.
+        def settled(checkout_mandate)
+          id = Lines.reference(checkout_mandate.line_items, @reference)
           Kiosk.configuration.after_payment&.call(id)
         rescue StandardError => e
           FailureLog.report("#{self.class} after_payment failed for #{id}", e)

data/lib/kiosk/server/pow_gate.rb

@@ -6,10 +6,10 @@ require 'json'
 module Kiosk
   module Server
     # The proof-of-work toll, in front of every verb that reaches the executor.
-    # It is paid once per access token: after one paid toll, every call made
-    # with that token proceeds until the token expires. With no
-    # `reputation_policy` it returns `:proceed` and touches nothing;
-    # `kiosk-reputation` is required only when a policy is set.
+    # The policy decides on each call; a valid proof sets the account's count of
+    # tolled calls back to zero. With no `reputation_policy` it returns
+    # `:proceed` and touches nothing; `kiosk-reputation` is required only when a
+    # policy is set.
     module PowGate
       module_function
 
@@ -21,46 +21,25 @@ module Kiosk
         )
       end
 
-      # `command` is the policy verb ({Executor::VERBS}); `verb` is the wire name
+      # `command` is the policy verb ({Executor::VERBS}); `verb` is the published name
       # the fingerprint binds.
-      def gate(identity:, command:, body:, pow:, method: 'POST', verb: nil) # rubocop:disable Metrics/ParameterLists -- the wire controller and the specs pass these six by name
+      def gate(identity:, command:, body:, pow:, method: 'POST', verb: nil) # rubocop:disable Metrics/ParameterLists -- WireController and the specs pass these six by name
         config = Kiosk.configuration
         policy = config.reputation_policy
-        return :proceed if policy.nil? || session_paid?(config, identity)
+        return :proceed if policy.nil?
 
-        secret = pow_secret!(config)
-        spec   = toll_for(policy, identity, command.to_sym)
+        secret  = pow_secret!(config)
+        factors = ReputationFactors.for(identity:, policy:)
+        spec    = policy.challenge_for(identity: identity, verb: command.to_sym, factors: factors)
         return :proceed if spec.nil?
 
         fp = request_fingerprint(method: method, verb: verb || command, body: body)
         PowToll.new(spec: spec, fingerprint: fp, secret: secret, config: config)
-               .collect!(pow).tap { paid(config, identity) }
-      end
-
-      def session_paid?(config, identity)
-        session = session_id(identity)
-        !session.nil? && config.pow_spent_store.spent?(session)
-      end
-
-      # Records the token's session as paid.
-      def paid(config, identity)
-        session = session_id(identity)
-        config.pow_spent_store.mark_spent(session, identity.claims[:exp]) if session
-      end
-
-      # The access token a toll pays for, by its `jti`, or nil for a caller without one.
-      def session_id(identity)
-        claims = identity&.claims || {}
-        "session:#{claims[:jti]}" if claims[:jti] && claims[:exp]
-      end
-
-      # The policy's toll for this caller and verb, or nil for none.
-      def toll_for(policy, identity, verb)
-        policy.challenge_for(identity: identity, verb: verb, factors: ReputationFactors.for(identity:, policy:))
+               .collect!(pow).tap { TolledCalls.reset!(identity.user_id) if factors.calls_since_proof }
       end
 
       def pow_secret!(config)
-        unless defined?(::Kiosk::Reputation)
+        unless defined?(::Kiosk::Reputation::Challenge)
           raise Errors::ConfigurationError,
                 'Kiosk::Server: reputation_policy is set but kiosk-reputation is not loaded. ' \
                 "Add `require 'kiosk/reputation'` (and `gem 'kiosk-reputation'`) to your app."

data/lib/kiosk/server/pow_spent_stores.rb

@@ -89,7 +89,7 @@ module Kiosk
         end
 
         def connection = ::ActiveRecord::Base.lease_connection
-        def table = %("#{Kiosk.configuration.schema}".pow_spent)
+        def table = %("#{Kiosk.configuration.schema}".kiosk_pow_spent)
       end
     end
   end

data/lib/kiosk/server/receipts.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The two AP2 v0.2 receipts a settled `pay` answers (§11.3): JWTs this
+    # operator signs as it signs a checkout, each naming its mandate by reference.
+    module Receipts
+      SUCCESS = 'Success'
+      # AP2 requires a network id; this text stands in when the PSP reports none.
+      NO_NETWORK_ID = 'not reported by the payment provider'
+
+      module_function
+
+      # @return [Hash] `checkout_receipt` and `payment_receipt`, compact JWTs
+      def issue(checkout:, payment:, settlement_id:, psp_reference:, network_confirmation_id:)
+        { checkout_receipt: sign(checkout, order_id: order_id(checkout)),
+          payment_receipt: sign(payment, payment_id: settlement_id, psp_confirmation_id: psp_reference,
+                                         network_confirmation_id: network_confirmation_id || NO_NETWORK_ID) }
+      end
+
+      # The id in the checkout's first line item, which names the item paid for (§11.7).
+      def order_id(checkout) = checkout.line_items.first.values.first.to_s
+
+      def sign(mandate, **claims)
+        Checkout.signed({ status: SUCCESS, iss: Kiosk.current_issuer, iat: Time.now.to_i,
+                          reference: mandate.reference, **claims })
+      end
+    end
+  end
+end

data/lib/kiosk/server/reputation_factors.rb

@@ -3,36 +3,43 @@
 module Kiosk
   module Server
     # The reputation inputs the engine knows itself: what the customer paid
-    # here and kept paid, and the visits the operator recorded, within a policy's window.
+    # here and kept paid, and the visits the operator recorded, within a policy's
+    # window; and the account's tolled calls since its last proof.
     module ReputationFactors
       module_function
 
       # Empty factors unless the policy names a window (`#within`, in seconds).
+      # Reading the factors counts an assistant's call as one more tolled call of its account.
       def for(identity:, policy:)
         return ::Kiosk::Reputation::Factors.empty unless policy.respond_to?(:within) && identity&.user_id
 
         count, cents = recent_spend(identity.user_id, Time.current - policy.within.to_i)
-        ::Kiosk::Reputation::Factors.empty.with(settled_purchases_count: count, settled_purchases_cents: cents)
+        ::Kiosk::Reputation::Factors.new(settled_purchases_count: count, settled_purchases_cents: cents,
+                                         calls_since_proof: identity.agent_id && TolledCalls.count!(identity.user_id))
       end
 
       # Settlements and visits of this customer since `since`: their count and their cents.
       # A settlement counts less what was refunded of it; one refunded in full does not count.
+      # The settlements and visits of each assistant account merged into this account count too.
       def recent_spend(user_id, since)
         sql = format(RECENT_SPEND_SQL, schema: Kiosk.configuration.schema)
         row = ::ActiveRecord::Base.lease_connection.exec_query(sql, 'Kiosk recent spend', [user_id, since]).to_a.first
         [row.fetch('count').to_i, row.fetch('cents').to_i]
       end
 
+      MERGED_SQL = 'SELECT user_id FROM "%<schema>s".kiosk_assistant_accounts WHERE merged_into = $1'
       RECENT_SPEND_SQL = <<~SQL.squish
         SELECT count(*) AS count, COALESCE(SUM(cents), 0) AS cents FROM (
           SELECT s.settled_amount_cents - COALESCE(SUM(r.refunded_amount_cents), 0) AS cents
-            FROM "%<schema>s".settlements s LEFT JOIN "%<schema>s".refunds r ON r.settlement_id = s.id
-            WHERE s.user_id = $1 AND s.settled_at >= $2 GROUP BY s.id
+            FROM "%<schema>s".kiosk_settlements s LEFT JOIN "%<schema>s".kiosk_refunds r ON r.settlement_id = s.id
+            WHERE (s.user_id = $1 OR s.user_id IN (#{MERGED_SQL})) AND s.settled_at >= $2 GROUP BY s.id
             HAVING s.settled_amount_cents > COALESCE(SUM(r.refunded_amount_cents), 0)
           UNION ALL
-          SELECT value_cents FROM "%<schema>s".visits WHERE user_id = $1 AND visited_at >= $2
+          SELECT value_cents FROM "%<schema>s".kiosk_visits
+            WHERE (user_id = $1 OR user_id IN (#{MERGED_SQL})) AND visited_at >= $2
         ) spend
       SQL
+      private_constant :MERGED_SQL
     end
   end
 end

data/lib/kiosk/server/request_validation.rb

@@ -15,11 +15,11 @@ module Kiosk
       # RESERVED-PLANE REQUEST BODY => the published object that types it.
       # The `/oauth/*` requests are form-encoded and have no schema.
       BODY_SCHEMAS = {
-        'POST <endpoint>/auth/register' => 'auth.schema.json#/$defs/credentialRequest',
-        'POST <endpoint>/auth/login' => 'auth.schema.json#/$defs/credentialRequest',
+        'POST <endpoint>/auth/rotate' => 'auth.schema.json#/$defs/rotationRequest',
         'POST <endpoint>/auth/claim' => 'binding.schema.json#/$defs/claimRequest',
         'POST <endpoint>/auth/unlink' => 'binding.schema.json#/$defs/unlinkRequest',
         'POST <endpoint>/agents/kyc' => 'kyc.schema.json#/$defs/request',
+        'POST <endpoint>/kyc/callback' => 'kyc.schema.json#/$defs/callback',
         'POST <endpoint>/pay' => 'mandates.schema.json#/$defs/payRequest'
       }.freeze
 
@@ -35,7 +35,7 @@ module Kiosk
         end
       end
 
-      # A missing member keeps the wire's own `missing field:` sentence.
+      # A missing member keeps the protocol's own `missing field:` sentence.
       def validate_body!(body, exchange:)
         return unless Kiosk.configuration.validate_requests
 

data/lib/kiosk/server/result.rb

@@ -3,7 +3,7 @@
 module Kiosk
   module Server
     # The executor's internal carrier for a successful call; only {#to_payload}
-    # reaches the wire, as the body.
+    # reaches the protocol, as the body.
     class Result < Data.define(:kind, :payload, :next_cursor, :total)
       KINDS = %i[rows value].freeze
 

data/lib/kiosk/server/revocation_stores.rb

@@ -7,6 +7,14 @@ module Kiosk
     # `revoked?(agent_id:, iat:)`: a token whose `iat` is strictly before the
     # agent's watermark is revoked.
     module RevocationStores
+      # Revokes every token of `agent_id` issued so far. JWT `iat` is whole
+      # seconds, the check is `iat < watermark`, and the IdP dates a token no
+      # earlier than the watermark, so the new watermark is the second after
+      # both now and the old watermark.
+      def self.revoke_issued(agent_id, store: Kiosk.configuration.revocation_store)
+        store.revoke_all(agent_id, at: [Time.now.to_i, store.watermark_for(agent_id).to_i].max + 1)
+      end
+
       # The default store: the `<schema>.revocations` table, shared by every
       # process and kept across restarts. A token of an unlinked or deleted
       # agent is revoked too.
@@ -50,7 +58,7 @@ module Kiosk
         private
 
         def connection = ::ActiveRecord::Base.lease_connection
-        def table(name) = %("#{Kiosk.configuration.schema}".#{name})
+        def table(name) = %("#{Kiosk.configuration.schema}".kiosk_#{name})
       end
     end
   end

data/lib/kiosk/server/routing.rb

@@ -38,7 +38,7 @@ module Kiosk
       end
 
       # The endpoint of one verb route. The controller action that declares the
-      # verb answers the wire request; the name is looked up per request, so a
+      # verb answers the protocol request; the name is looked up per request, so a
       # development reload is served. A name that no action answers goes to
       # {VerbController}, which refuses it.
       class VerbRoute