kiosk-server 0.6.1 → 0.6.28

data/lib/kiosk/server/configuration_extension.rb

@@ -8,7 +8,7 @@ module Kiosk
       # cannot each build their own store (a double-spent proof of work).
       LAZY_STORE_MUTEX = Mutex.new
 
-      # The discovery settings: where the wire is mounted and what it advertises.
+      # The discovery settings: where the protocol is mounted and what it advertises.
       module Discovery
         # Default `/kiosk`. Discovery advertises `endpoint = origin + mount_path`.
         attr_writer :mount_path
@@ -30,13 +30,18 @@ module Kiosk
           @owner ||= {}
         end
 
-        # The skill this origin was built against. Discovery emits the `skill`
-        # block only when `skill_sha256` is set.
+        # The skill cut of this kiosk-server release. Each release gives the cut
+        # of its own version. Do not set it.
         attr_writer :skill_url
 
         def skill_url
-          @skill_url ||= 'https://kiosk.tech/skill-v0.6.1.md'
+          @skill_url ||= 'https://kiosk.tech/skill-v0.6.28.md'
         end
+
+        # The SHA-256 of the file at `skill_url`, as hex. Default nil: discovery
+        # then advertises no `skill` block. Make it with
+        # `curl -fsS <skill_url> | shasum -a 256`. Kiosk::TestHelpers::SkillPin
+        # fails when an update of kiosk-server changes `skill_url`.
         attr_accessor :skill_sha256
 
         private
@@ -107,41 +112,15 @@ module Kiosk
         def kyc_claims
           @kyc_claims || []
         end
-
-        # Must match the `iss` of submitted KYC attestations.
-        attr_writer :kyc_issuer
-
-        def kyc_issuer
-          @kyc_issuer
-        end
-
-        # The `aud` a KYC attestation must carry. Default: the origin being served.
-        attr_writer :kyc_audience
-
-        def kyc_audience
-          @kyc_audience || Kiosk.current_issuer
-        end
-
-        # The KYC provider's Ed25519 public key: an OpenSSL::PKey or a PEM string.
-        def kyc_public_key
-          @kyc_public_key
-        end
-
-        def kyc_public_key=(value)
-          @kyc_public_key = value.is_a?(String) ? OpenSSL::PKey.read(value) : value
-          return if @kyc_public_key.nil? || Jwk.ed25519?(@kyc_public_key)
-
-          raise ArgumentError, "kyc_public_key must be an Ed25519 key or its PEM string, got #{@kyc_public_key.class}"
-        end
       end
 
       # The database settings: where Kiosk's tables live and how a request reaches them.
       module Database
-        # Postgres schema for Kiosk's own tables and functions. Default 'kiosk'.
+        # The Postgres schema of Kiosk's `kiosk_*` tables. Default 'public'.
         attr_writer :schema
 
         def schema
-          @schema ||= 'kiosk'
+          @schema ||= 'public'
         end
 
         # Prefix of the session GUCs a request sets, e.g. `app.user_id`. Default 'app'.
@@ -252,16 +231,14 @@ module Kiosk
       # `account`, a `user_model` record, and its tokens are revoked.
       attr_accessor :assistant_unlinked
 
-      # Optional `(agent_id:) → { amount_cents:, currency: } | nil`, checked
-      # before capture; 0 blocks payments, and so does a checkout in another currency.
+      # Optional `(agent_id:) → { amount_cents:, currency: } | nil`: the most
+      # one `pay` may charge, checked before capture. 0 blocks payments, and so
+      # does a checkout in another currency.
       # {Kiosk::Server::ColumnSpendingCap} reads
       # `agents.spending_cap_cents`, the column edited by the manage-assistants
       # page, and `agents.spending_cap_currency`.
       attr_accessor :spending_cap
 
-      # Days of settled spend summed against the cap. Default nil: all time.
-      attr_accessor :spending_cap_window_days
-
       # `call(id, lines) → cents | String`: the payable row's price, or why the checkout is refused.
       attr_accessor :checkout_price_checker
 
@@ -310,7 +287,7 @@ module Kiosk
           LAZY_STORE_MUTEX.synchronize { @pow_spent_store ||= Kiosk::Server::PowSpentStores::ActiveRecord.new }
       end
 
-      # Seconds an access token lives. One paid proof-of-work toll lasts as long. Default 3600.
+      # Seconds an access token lives. Default 3600.
       attr_writer :access_token_ttl
 
       def access_token_ttl

data/lib/kiosk/server/current_request.rb

@@ -2,7 +2,7 @@
 
 module Kiosk
   module Server
-    # The wire request being dispatched, visible to its handler for the duration
+    # The protocol request being dispatched, visible to its handler for the duration
     # of one block. Fiber-local: a handler that hands work to another thread must
     # pass what it needs.
     module CurrentRequest

data/lib/kiosk/server/device_authorization.rb

@@ -5,7 +5,7 @@ require 'digest'
 
 module Kiosk
   module Server
-    # One account-binding request on the RFC 8628 device-grant wire: a `:claim`
+    # One account-binding request on the RFC 8628 device-grant endpoints: a `:claim`
     # the agent opens and a human approves, or a `:link` a signed-in human
     # creates already approved. Only SHA-256 digests of its two codes are kept.
     #

data/lib/kiosk/server/device_authorization_stores.rb

@@ -147,7 +147,7 @@ module Kiosk
         private
 
         def connection = ::ActiveRecord::Base.lease_connection
-        def table = %("#{Kiosk.configuration.schema}".device_authorizations)
+        def table = %("#{Kiosk.configuration.schema}".kiosk_device_authorizations)
 
         def insert_sql
           placeholders = (1..COLUMNS.size).map { |i| "$#{i}" }.join(', ')

data/lib/kiosk/server/device_code_grant.rb

@@ -2,7 +2,7 @@
 
 module Kiosk
   module Server
-    # The claim ceremony on the RFC 8628 device-grant wire: binds a registered
+    # The claim ceremony on the RFC 8628 device-grant endpoints: binds a registered
     # client to an existing human account once the human approves.
     #
     #   .start     — POST /oauth/device_authorization
@@ -42,7 +42,7 @@ module Kiosk
           expires_in: expires_in, interval: DEFAULT_POLL_INTERVAL, da: da }
       end
 
-      # The first poll of each device code value pays the auth toll; later polls
+      # The first poll of each device code value is tolled; later polls
       # of that value are free until any code could have expired. The store is
       # not read first, so an unknown code costs the same work as a live one.
       def pay_toll!(device_code, pow, now: Time.current)

data/lib/kiosk/server/dpop.rb

@@ -23,7 +23,12 @@ module Kiosk
       module_function
 
       # The `WWW-Authenticate` value of a 401 on a request that needs a token.
-      def challenge = %(#{SCHEME} algs="#{AssistantKey.algorithms.join(' ')}")
+      # `resource_metadata` names the protected-resource metadata (RFC 9728
+      # Section 5.1).
+      def challenge
+        %(#{SCHEME} algs="#{AssistantKey.algorithms.join(' ')}", ) +
+          %(resource_metadata="#{Kiosk.current_issuer}/.well-known/oauth-protected-resource")
+      end
 
       def hint
         'send `Authorization: DPoP <access_token>` and one `DPoP` header: a JWS with typ dpop+jwt, ' \

data/lib/kiosk/server/engine.rb

@@ -29,7 +29,7 @@ module Kiosk
                                      Kiosk::Server::IssuerMiddleware
       end
 
-      # Credential-bearing wire fields, kept out of the `Parameters:` log line.
+      # Credential-bearing protocol fields, kept out of the `Parameters:` log line.
       # Whole-key matches, so an operator's own `promo_code` is left alone.
       FILTERED_PARAMETERS = %w[
         client_assertion new_client_assertion code device_code kyc_jws
@@ -155,7 +155,7 @@ module Kiosk
       end
 
       routes do
-        # The wire's reserved endpoints. The mount is drawn first in the host's
+        # The protocol's reserved endpoints. The mount is drawn first in the host's
         # routes, so these win by first-match. Optional modules are drawn
         # unconditionally and answer `module_not_served` (501) when not configured.
         # `schema` resolves no identity — it is PUBLIC, like `openapi.json`

data/lib/kiosk/server/errors.rb

@@ -2,10 +2,10 @@
 
 module Kiosk
   module Server
-    # The wire error contract: the closed `code` vocabulary and the problem
+    # The Kiosk error contract: the closed `code` vocabulary and the problem
     # document (RFC 9457) every refusal is rendered as.
     module Errors
-      # The wire's seventeen refusal codes and their HTTP status (spec §9). Adding one is a spec change first.
+      # The protocol's seventeen refusal codes and their HTTP status (spec §9). Adding one is a spec change first.
       CODES = {
         'bad_request' => 400,
         'unauthenticated' => 401,
@@ -119,7 +119,7 @@ module Kiosk
       end
 
       # What a Rails-native raise answers with: our sentence for the decided code.
-      # The exception's own text goes to the operator's log, never to the wire.
+      # The exception's own text goes to the operator's log, never to the protocol.
       # One entry per {STATUS_CODES} value.
       module Rescued
         DETAILS = {
@@ -156,7 +156,7 @@ module Kiosk
       RESCUED_DETAILS = Rescued::DETAILS
       RESCUED_HINTS = Rescued::HINTS
 
-      # @return [Hash] `{code:, message:, hint:}` of the wire error a rescued exception becomes
+      # @return [Hash] `{code:, message:, hint:}` of the Kiosk error a rescued exception becomes
       def self.rescued_wire(code, verb: nil) = Rescued.wire(code, verb)
 
       class Base < StandardError
@@ -191,7 +191,7 @@ module Kiosk
         end
       end
 
-      # A wire error named by its code rather than its class. `extra:` adds extension members;
+      # A Kiosk error named by its code rather than its class. `extra:` adds extension members;
       # the members the code and message decide stay theirs, and `instance` is never emitted (§9).
       class WireError < Base
         DECIDED = %i[type title status detail instance code hint].freeze
@@ -200,7 +200,7 @@ module Kiosk
           code = code.to_s
           unless CODES.key?(code)
             raise ArgumentError,
-                  "unknown wire code #{code.inspect} — the vocabulary is Errors::CODES, closed by the spec"
+                  "unknown error code #{code.inspect} — the vocabulary is Errors::CODES, closed by the spec"
           end
 
           super(message, hint: hint)
@@ -238,6 +238,20 @@ module Kiosk
         def response_headers = { 'WWW-Authenticate' => Dpop.challenge }
       end
 
+      # The 401 of a refused client assertion (RFC 7523). No registered scheme names one.
+      class ClientAssertionRefused < Unauthenticated
+        def self.challenge = %(Kiosk-Client-Assertion realm="#{Kiosk.current_issuer}")
+
+        def response_headers = { 'WWW-Authenticate' => self.class.challenge }
+      end
+
+      # The 401 of a binding path or engine page that the provider's own sign-in session authenticates.
+      class SessionRequired < Unauthenticated
+        def self.challenge = %(Kiosk-Session realm="#{Kiosk.current_issuer}")
+
+        def response_headers = { 'WWW-Authenticate' => self.class.challenge }
+      end
+
       class Forbidden < Base
         CODE        = 'forbidden'
         HTTP_STATUS = 403
@@ -280,7 +294,7 @@ module Kiosk
         HTTP_STATUS = 403
       end
 
-      # The acting assistant's spending cap would be exceeded; checked before capture.
+      # The checkout is above the acting assistant's spending cap, or in another currency; checked before capture.
       class SpendingCapExceeded < Base
         CODE        = 'spending_cap_exceeded'
         HTTP_STATUS = 403

data/lib/kiosk/server/event_stores.rb

@@ -83,7 +83,7 @@ module Kiosk
           SQL
         end
 
-        # The wire's five event members, string-keyed, as {EventStore} gives them.
+        # The protocol's five event members, string-keyed, as {EventStore} gives them.
         def to_event(row)
           {
             'id' => row['id'].to_i,
@@ -114,7 +114,7 @@ module Kiosk
           prune! if due
         end
 
-        def table = %("#{Kiosk.configuration.schema}".events)
+        def table = %("#{Kiosk.configuration.schema}".kiosk_events)
 
         # `connection` raises under `permanent_connection_checkout = :disallowed`.
         def connection = ::ActiveRecord::Base.lease_connection

data/lib/kiosk/server/events.rb

@@ -28,11 +28,12 @@ module Kiosk
 
         def known = registry.keys.sort
 
-        # Published beside `queries` and `actions`; `subject_reachable` is the operator's rule, not wire.
+        # Published beside `queries` and `actions`; `subject_reachable` is the operator's rule, not protocol.
         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.
+        # subscribing; `identity_scope` names who is told about this transition. The id is taken
+        # here and seen at commit, so call it as the last step of the transaction (spec Section 8.5.5).
         # @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)
@@ -70,7 +71,7 @@ module Kiosk
 
         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 ' \
+            'published name and one payload shape; declare it once, on the controller that owns ' \
             'the transition it reports.'
         end
 

data/lib/kiosk/server/events_connection.rb

@@ -61,6 +61,15 @@ module Kiosk
         end
       end
 
+      # Spec Section 3, point 6: the 101 answer carries the version headers. The
+      # WebSocket driver writes it past every middleware, and Action Cable gives
+      # no other way to set its headers than the driver it keeps.
+      def initialize(...)
+        super
+        driver = websocket.send(:websocket)&.instance_variable_get(:@driver)
+        Headers.build.each { |name, value| driver.set_header(name, value) } if driver
+      end
+
       def connect
         identity = resolve_identity || reject_unauthorized_connection
         @kiosk_identity = identity
@@ -105,14 +114,21 @@ module Kiosk
       def kiosk_credential_holds?
         return true if token_holds?
 
-        if kiosk_credential_expired?
-          close(reason: 'token_expired', reconnect: true)
-        else
-          close(reason: 'revoked', reconnect: false)
-        end
+        expired = kiosk_credential_expired?
+        close(reason: expired ? 'token_expired' : 'revoked', reconnect: expired)
         false
       end
 
+      # A subscription the upgrade URL declares joins the URL's replay group;
+      # one a `subscribe` frame declares replays alone (§8.5.5).
+      def kiosk_replay_member(floor, &)
+        member = @kiosk_url_replay&.join(floor, &)
+        return member if member
+
+        group = EventsReplay.new(kiosk_identity_key)
+        group.join(floor, &).tap { group.close }
+      end
+
       private
 
       def reauthorise!
@@ -151,9 +167,11 @@ module Kiosk
       end
 
       def auto_subscribe!
+        @kiosk_url_replay = EventsReplay.new(kiosk_identity_key)
         UrlSubscriptions.identifiers(request.query_string).each do |identifier|
           subscriptions.execute_command('command' => 'subscribe', 'identifier' => identifier)
         end
+        @kiosk_url_replay.close
       end
 
       # The token and the DPoP proof of the upgrade request.

data/lib/kiosk/server/events_replay.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Delivery in id order (spec Section 8.5.5). The subscriptions one upgrade
+    # URL declares form one group; a `subscribe` frame forms a group of one.
+    # When every member is confirmed, the group replays the members' committed
+    # tail in one ascending pass. Until then it holds their live events, and
+    # after the replay it sends those it did not replay, in id order. An event
+    # that commits after a higher id is outside this order (the same section).
+    class EventsReplay
+      # One subscription in the group. `floor` is the cursor it replays after.
+      Member = Struct.new(:group, :floor, :deliver) do
+        delegate :confirmed, to: :group
+
+        def live(event) = group.live(self, event)
+      end
+
+      def initialize(identity_key)
+        @identity_key = identity_key
+        @mutex = Mutex.new
+        @members = []
+        @confirmed = 0
+        @open = true
+        @held = []
+        @replayed = false
+      end
+
+      # Adds a member while the group is open; nil after {#close}.
+      # `deliver` transmits an event when the subscription wants it.
+      def join(floor, &deliver)
+        @mutex.synchronize do
+          next unless @open
+
+          Member.new(self, floor, deliver).tap { |member| @members << member }
+        end
+      end
+
+      # No member joins after this.
+      def close = settle { @open = false }
+
+      def confirmed = settle { @confirmed += 1 }
+
+      def live(member, event)
+        @mutex.synchronize do
+          @replayed ? member.deliver.call(event) : @held << [member, event]
+        end
+      end
+
+      private
+
+      def settle
+        @mutex.synchronize do
+          yield
+          replay! if !@open && !@replayed && @members.any? && @confirmed == @members.size
+        end
+      end
+
+      def replay!
+        tail = Kiosk.configuration.event_store.since(@identity_key, @members.map(&:floor).min)
+        tail.each { |event| offer(event) }
+        release_held(tail.to_set { |event| event['id'] })
+        @replayed = true
+      end
+
+      # A held event the replay already offered this member is not sent again.
+      def release_held(replayed)
+        @held.sort_by { |_, event| event['id'] }.each do |member, event|
+          member.deliver.call(event) unless replayed.include?(event['id']) && event['id'] > member.floor
+        end
+        @held = nil
+      end
+
+      def offer(event)
+        @members.each { |member| member.deliver.call(event) if event['id'] > member.floor }
+      end
+    end
+  end
+end

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

@@ -33,7 +33,7 @@ module Kiosk
           settlement_result(chain, row.fetch('settlement_id'), settled, row.fetch('currency'))
         end
 
-        # A refusal under which no money moved: the checkout stops counting against the spending cap.
+        # A refusal under which no money moved: a new pair can pay the checkout.
         def decline(chain)
           SessionContext.open(connection: connection, identity: identity) { decline_checkout(chain.checkout_row) }
         end

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

@@ -3,21 +3,16 @@
 module Kiosk
   module Server
     class Executor
-      # The assistant's spending cap, checked at pay time.
+      # The assistant's spending cap: the most one `pay` may charge, checked before capture.
       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 checkout
-        # mandate, under a per-assistant lock, so two concurrent pays see each
-        # other: the second counts the first's checkout as in flight. A checkout
-        # mandate already recorded is a repeat and adds nothing.
+        # another currency. A checkout mandate already recorded is a repeat: the
+        # first `pay` of that checkout passed this check.
         def enforce_spending_cap!(checkout)
           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 checkout_recorded?(checkout)
+          return if cap.nil? || checkout_recorded?(checkout)
 
           refuse_other_currency!(cap.fetch(:currency), checkout)
           refuse_over_cap!(cap.fetch(:amount_cents).to_i, checkout)
@@ -32,69 +27,16 @@ module Kiosk
         end
 
         def refuse_over_cap!(cap, checkout)
-          window_days = Kiosk.configuration.spending_cap_window_days
-          spent = spent_in_window(checkout, window_days)
-          return if spent + checkout.total_amount_cents <= cap
-
-          raise Errors::SpendingCapExceeded.new('assistant spending cap exceeded', hint: cap_hint(cap, spent, window_days, checkout))
-        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(checkout, window_days)
-          binds = spent_binds(identity.agent_id, checkout.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, checkout)
-          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 #{checkout.total_amount_cents}"
-        end
+          return if checkout.total_amount_cents <= cap
 
-        # 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
-
-        # Checkout mandates of this agent that are live, 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}.checkout_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.checkout_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
+          raise Errors::SpendingCapExceeded.new('assistant spending cap exceeded',
+                                                hint: "one payment may charge #{cap} cents at most; this charge is #{checkout.total_amount_cents} cents")
         end
 
         def checkout_recorded?(checkout)
-          sql = "SELECT 1 FROM #{Kiosk.configuration.schema}.checkout_mandates WHERE user_id = $1 AND reference = $2"
+          sql = "SELECT 1 FROM #{Kiosk.configuration.schema}.kiosk_checkout_mandates WHERE user_id = $1 AND reference = $2"
           connection.exec_query(sql, 'Kiosk checkout mandate recorded', [checkout.user_id, checkout.reference]).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

data/lib/kiosk/server/executor.rb

@@ -4,7 +4,7 @@ module Kiosk
   module Server
     # Runs one call for an identity inside a {SessionContext}; returns a {Result} or raises {Errors::Base}.
     class Executor
-      # The coarse kinds of call shared by the toll, the policy and this dispatcher; not wire paths.
+      # The coarse kinds of call shared by the toll, the policy and this dispatcher; not HTTP paths.
       VERBS = %i[query run pay].freeze
 
       # Kinds with an irreversible external effect (a PSP capture) that manage their own transactions.
@@ -121,7 +121,7 @@ module Kiosk
         result
       end
 
-      # The handler's message goes to the operator's log, never onto the wire.
+      # The handler's message goes to the operator's log, never onto the protocol.
       def report_handler_failure(kind, name, error)
         FailureLog.report("#{kind} #{name.inspect} raised #{error.class}", error)
       end
@@ -220,7 +220,7 @@ module Kiosk
         end
 
         # Phase 2: the irreversible capture. A refusal under which no money moved
-        # declines the checkout mandate, so it stops counting against the spending cap.
+        # declines the checkout mandate, so a new pair can pay that checkout.
         def capture(provider, chain)
           charge(provider, chain)
         rescue Kiosk::PaymentProviders::SetupRequired
@@ -280,9 +280,9 @@ module Kiosk
           SELECT c.id AS checkout_row, c.declined_at,
                  s.id AS settlement_id, s.psp_reference, s.settled_amount_cents, s.currency,
                  s.network_confirmation_id
-          FROM %<schema>s.checkout_mandates c
-          JOIN %<schema>s.payment_mandates p ON p.checkout_mandate_id = c.id
-          LEFT JOIN %<schema>s.settlements s ON s.checkout_mandate_id = c.id
+          FROM %<schema>s.kiosk_checkout_mandates c
+          JOIN %<schema>s.kiosk_payment_mandates p ON p.checkout_mandate_id = c.id
+          LEFT JOIN %<schema>s.kiosk_settlements s ON s.checkout_mandate_id = c.id
           WHERE c.user_id = $1 AND p.user_id = $1
             AND c.reference = $2
             AND c.sd_jwt = $3
@@ -292,7 +292,7 @@ module Kiosk
 
         # `line_items` arrives as JSON text; the cast stores a jsonb array rather than a string.
         CHECKOUT_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.checkout_mandates
+          INSERT INTO %<schema>s.kiosk_checkout_mandates
             (reference, checkout_hash, user_id, agent_id, issuer, line_items,
              total_amount_cents, currency, expires_at, created_at, sd_jwt)
           VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8, $9, now(), $10)
@@ -300,7 +300,7 @@ module Kiosk
         SQL
 
         PAYMENT_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.payment_mandates
+          INSERT INTO %<schema>s.kiosk_payment_mandates
             (reference, checkout_mandate_id, user_id, agent_id, issuer,
              payment_instrument, amount_cents, currency, expires_at, created_at, sd_jwt)
           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, now(), $10)
@@ -309,7 +309,7 @@ module Kiosk
 
         # Nobody signs a settlement; `UNIQUE (checkout_mandate_id)` keeps it single.
         SETTLEMENT_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.settlements
+          INSERT INTO %<schema>s.kiosk_settlements
             (checkout_mandate_id, user_id, agent_id, issuer, psp_reference,
              settled_amount_cents, currency, network_confirmation_id, settled_at)
           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, now())
@@ -317,7 +317,7 @@ module Kiosk
         SQL
 
         DECLINE_SQL = <<~SQL.squish
-          UPDATE %<schema>s.checkout_mandates SET declined_at = now() WHERE id = $1 AND declined_at IS NULL
+          UPDATE %<schema>s.kiosk_checkout_mandates SET declined_at = now() WHERE id = $1 AND declined_at IS NULL
         SQL
 
         private

data/lib/kiosk/server/failure_log.rb

@@ -2,18 +2,18 @@
 
 module Kiosk
   module Server
-    # Logs the exception whose message a refusal kept off the wire: Rails' logger, else `warn`.
+    # Logs the exception whose message a refusal kept out of the response: Rails' logger, else `warn`.
     # A raising logger is swallowed so one failure does not become two.
     module FailureLog
       # Enough frames to reach the operator's own code without flooding the log.
       BACKTRACE_FRAMES = 20
 
-      # One string to grep for refusals that kept their message off the wire.
+      # One string to grep for refusals that kept their message off the protocol.
       PREFIX = '[kiosk-server]'
 
       module_function
 
-      # `summary` is the caller's own words, the half that also reaches the wire.
+      # `summary` is the caller's own words, the half that also reaches the protocol.
       def report(summary, error)
         line = "#{PREFIX} #{summary}: #{error.message}\n  " \
                "#{Array(error.backtrace).first(BACKTRACE_FRAMES).join("\n  ")}"