kiosk-server 0.6.1 → 0.6.28

data/lib/kiosk/server/handler_mixin.rb

@@ -5,8 +5,8 @@ require 'action_dispatch'
 
 module Kiosk
   module Server
-    # Implementation behind `include Kiosk::Handler`. The macros above a `def` make it a wire verb;
-    # a method with no pending declaration stays off the wire.
+    # Implementation behind `include Kiosk::Handler`. The macros above a `def` make it a verb;
+    # a method with no pending declaration stays off the protocol.
     module HandlerMixin
       KINDS = %i[action query].freeze
 
@@ -38,7 +38,7 @@ module Kiosk
         base.extend(ClassMethods)
         base.include(InstanceMethods)
 
-        # The wire authenticates by bearer token, never by cookie, so CSRF protection does not apply.
+        # The protocol authenticates by bearer token, never by cookie, so CSRF protection does not apply.
         base.skip_forgery_protection if base.respond_to?(:skip_forgery_protection)
 
         # Registered at include time, so an operator's own `rescue_from` declared later wins.
@@ -80,7 +80,7 @@ module Kiosk
 
         def bad_topic_name(owner, name)
           "#{owner} declared `topic #{name.inspect}`, which is not a legal Kiosk name. " \
-            "A topic name is a wire name: #{NAME_PATTERN.inspect}."
+            "A topic name matches #{NAME_PATTERN.inspect}."
         end
 
         def reserved_topic(owner, name)
@@ -300,12 +300,12 @@ module Kiosk
           kiosk_declare(method_name, pending)
         end
 
-        # Wire name → declaration for the verbs on this class, one per name.
+        # Published name → declaration for the verbs on this class, one per name.
         def kiosk_declarations
           @kiosk_declarations ||= {}
         end
 
-        # Wire name → declaration for the topics on this class.
+        # Published name → declaration for the topics on this class.
         def kiosk_topic_declarations
           @kiosk_topic_declarations ||= {}
         end
@@ -361,7 +361,7 @@ module Kiosk
 
         private
 
-        # The acting {Kiosk::Identity}; nil outside a wire request.
+        # The acting {Kiosk::Identity}; nil outside a protocol request.
         def kiosk_identity = CurrentRequest.identity
 
         # Differs from the method name only under `wire_name`.
@@ -376,8 +376,8 @@ module Kiosk
         end
 
         # A validation failure answers 400 with the errors' full messages. Any other raise Rails knows
-        # a status for maps to its lone wire code, its own message going to the operator's log and
-        # never onto the wire; anything else is re-raised.
+        # a status for maps to its lone error code, its own message going to the operator's log and
+        # never onto the protocol; anything else is re-raised.
         def kiosk_rescue_to_wire(exception)
           raise exception if exception.is_a?(Kiosk::Server::Errors::Base)
 

data/lib/kiosk/server/handler_registrations.rb

@@ -18,7 +18,7 @@ module Kiosk
           load_handlers_dir
           handlers.select! { |name| name.safe_constantize&.kiosk_register! }
           PaymentSetup.register! if Kiosk.configuration.payment_provider
-          Kyc.register! if Kiosk.configuration.kyc_provider
+          Kyc.register! if Kiosk.configuration.kyc_provider&.opens_verifications?
           refuse_cross_kind_collisions!
         end
 

data/lib/kiosk/server/handler_serving.rb

@@ -5,17 +5,17 @@ require 'json'
 module Kiosk
   module Server
     # How a controller that includes {Kiosk::Handler} answers a verb call.
-    # {Routing::VerbRoute} sends the wire request to the action that declares
+    # {Routing::VerbRoute} sends the protocol request to the action that declares
     # the verb. Around that action this module runs the gates of {VerbWire},
     # the session and the transaction, and writes the action's render as the
-    # wire answer.
+    # protocol answer.
     module HandlerServing
       include VerbWire
 
-      # The Rack env key where {Routing::VerbRoute} puts the wire name it routed.
+      # The Rack env key where {Routing::VerbRoute} puts the published name it routed.
       VERB_KEY = 'kiosk.verb'
 
-      # The one header of an action's render that reaches the wire: `Cache-Control`, on a 2xx (§3.7.4).
+      # The one header of an action's render that reaches the response: `Cache-Control`, on a 2xx (§3.7.4).
       PROPAGATED_HEADERS = %w[Cache-Control].freeze
 
       private
@@ -34,7 +34,7 @@ module Kiosk
         kiosk_render_refusal(Errors.malformed_json(hint: BODY_HINT))
       end
 
-      # The verb's {Result}: the wire's gates, then the action inside the session.
+      # The verb's {Result}: the protocol's gates, then the action inside the session.
       def kiosk_call(declaration, &)
         kind     = declaration[:kind]
         name     = @_kiosk_wire_name = declaration[:wire_name]
@@ -55,7 +55,7 @@ module Kiosk
         Answer.new(kind, @_kiosk_wire_name).value(status, kiosk_read_body(body), @_kiosk_page)
       end
 
-      # The action's `params` are the decoded arguments; the wire answers JSON whatever the caller's
+      # The action's `params` are the decoded arguments; the protocol answers JSON whatever the caller's
       # `Accept`, so an action's template is its `.json` one.
       def kiosk_wire_parameters!(args)
         request.set_header('action_dispatch.request.request_parameters', args.dup)
@@ -89,7 +89,7 @@ module Kiosk
         render_wire_error(error)
       end
 
-      # The action's render was read; the wire answer is written into a fresh response.
+      # The action's render was read; the protocol answer is written into a fresh response.
       def kiosk_fresh_response!
         set_response!(self.class.make_response!(request))
         @_response_body = nil
@@ -98,7 +98,7 @@ module Kiosk
       # A route drawn straight at a handler action, not through `kiosk do`, answers 404 `verb_not_found`.
       def kiosk_refuse_unrouted
         problem = Errors::VerbNotFound.new(
-          'Kiosk handlers are reachable through the Kiosk wire only',
+          'Kiosk handlers are reachable through the Kiosk HTTP API only',
           hint: "call the verb's own route — " \
                 "GET #{Kiosk.configuration.mount_path}/<query-name> or " \
                 "POST #{Kiosk.configuration.mount_path}/<action-name>"
@@ -107,7 +107,7 @@ module Kiosk
         render json: problem, status: :not_found, content_type: Errors::PROBLEM_CONTENT_TYPE
       end
 
-      # An action's render as the verb's answer: its payload, or the wire error it means.
+      # An action's render as the verb's answer: its payload, or the Kiosk error it means.
       class Answer
         def initialize(kind, wire_name)
           @kind      = kind
@@ -125,7 +125,7 @@ module Kiosk
 
         private
 
-        # 2xx → the rendered JSON; otherwise the wire error it means.
+        # 2xx → the rendered JSON; otherwise the Kiosk error it means.
         def decode(status, raw)
           return parse_json(raw) if status >= 200 && status < 300
 
@@ -172,7 +172,7 @@ module Kiosk
           raise Errors::ActionFailed.new(
             "#{@kind} #{@wire_name.inspect} rendered a non-JSON body",
             hint: 'a Kiosk handler answers with `render json:` — HTML, redirects and ' \
-                  '`send_file` have no place on the wire'
+                  '`send_file` have no place in a Kiosk response'
           )
         end
 

data/lib/kiosk/server/headers.rb

@@ -2,7 +2,7 @@
 
 module Kiosk
   module Server
-    # The Kiosk response headers and the cache policy of a wire response.
+    # The Kiosk response headers and the cache policy of a Kiosk response.
     module Headers
       def self.add_to(headers, server_version: Kiosk::Server::VERSION)
         headers[Kiosk::Protocol::HEADER_SERVER_VERSION] = server_version
@@ -18,7 +18,7 @@ module Kiosk
       # §3.7.1: every one of these changes the answer and none is in the URL.
       WIRE_VARY = %w[Authorization Kiosk-PoW Kiosk-Timezone].freeze
 
-      # Adds the wire `Vary`; forces `no-store` on a 402; defaults to
+      # Adds the protocol `Vary`; forces `no-store` on a 402; defaults to
       # `private, no-store` and refuses a shared-cache directive (§3.7.3).
       def self.add_cache_policy(headers, status:)
         add_wire_vary(headers)
@@ -56,7 +56,7 @@ module Kiosk
         'Sent `private, no-store` instead; send `private, max-age=N` to let the caller cache it.'
 
       def self.refuse_shared_cache(value)
-        message = '[kiosk-server] refused a shared-cache policy on a wire response: ' \
+        message = '[kiosk-server] refused a shared-cache policy on a Kiosk response: ' \
                   "Cache-Control: #{value.inspect}. #{SHARED_CACHE_RULE}"
         logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
         logger ? logger.warn(message) : warn(message)

data/lib/kiosk/server/identity_resolution.rb

@@ -2,7 +2,7 @@
 
 module Kiosk
   module Server
-    # The identity of a wire or event-stream caller: the access token, read by
+    # The identity of a protocol or event-stream caller: the access token, read by
     # the configured agent IdP or the bundled one. A cookie session
     # reaches only the human-side pages and the binding endpoints.
     module IdentityResolution

data/lib/kiosk/server/kyc.rb

@@ -49,7 +49,7 @@ module Kiosk
         def claims = Array(Kiosk.configuration.kyc_claims).map(&:to_s)
 
         def served!
-          return if provider
+          return if provider&.opens_verifications?
 
           raise Errors::ModuleNotServed.new(
             'this operator does not serve the KYC module',
@@ -115,8 +115,8 @@ module Kiosk
 
         # Names only a path this origin serves.
         def gate_hint
-          return REQUEST_HINT if provider
-          return ATTEST_HINT if Kiosk.configuration.kyc_public_key
+          return REQUEST_HINT if provider&.opens_verifications?
+          return ATTEST_HINT if provider
 
           CLOSED_HINT
         end
@@ -148,9 +148,7 @@ module Kiosk
           private
 
           def open_verification(user_id)
-            Kyc.provider.open_verification(subject: user_id, claims: Kyc.claims,
-                                           audience: Kiosk.configuration.kyc_audience.to_s,
-                                           callback_url: Kyc.callback_url)
+            Kyc.provider.open_verification(subject: user_id, claims: Kyc.claims, callback_url: Kyc.callback_url)
           rescue Kiosk::KycProviders::Unavailable => e
             FailureLog.report("#{NAME} could not open a verification", e)
             raise Errors::WireError.new(
@@ -249,7 +247,7 @@ module Kiosk
                     JSON.generate(attributes), user_id.to_s)
           end
 
-          def table(name) = connection.quote_table_name("#{Kiosk.configuration.schema}.#{name}")
+          def table(name) = connection.quote_table_name("#{Kiosk.configuration.schema}.kiosk_#{name}")
 
           def execute(sql, *binds) = connection.exec_query(sql, 'Kiosk KYC', binds).to_a
 

data/lib/kiosk/server/kyc_verifier.rb

@@ -4,10 +4,10 @@ require 'jwt'
 
 module Kiosk
   module Server
-    # Verifies a KYC attestation JWS against `kyc_public_key`: `iss`, `aud`,
-    # `sub` and `level: "verified"` must match, and the configured
-    # `kyc_provider` must accept it; only attributes
-    # that are literally `true` are granted.
+    # Verifies a KYC attestation JWS against the configured `kyc_provider`: its
+    # key signs it, its `iss` and `aud` match, `sub` and `level: "verified"`
+    # match, and the provider accepts it; only attributes that are literally
+    # `true` are granted.
     module KycVerifier
       # Named once for the decode and the published hint.
       REQUIRED_CLAIMS = %w[exp iss aud sub].freeze
@@ -19,17 +19,17 @@ module Kiosk
       module_function
 
       def verify(raw_jws:, subject:)
-        config  = Kiosk.configuration
-        payload = decode(raw_jws, config)
-        check_issuer!(payload, config)
+        provider = provider!
+        payload  = decode(raw_jws, provider)
+        check_issuer!(payload, provider)
         # Binds the attestation to this operator.
-        if payload[:aud].to_s != config.kyc_audience.to_s
+        if payload[:aud].to_s != provider.audience
           raise Errors::Forbidden.new('KYC attestation audience mismatch',
-                                      hint: audience_hint(payload, config))
+                                      hint: audience_hint(payload, provider))
         end
 
         check_subject!(payload, subject)
-        check_provider!(payload, config)
+        check_provider!(payload, provider)
 
         payload.merge(attributes: verified_attributes(payload[:attributes]))
       end
@@ -47,8 +47,8 @@ module Kiosk
       end
 
       # The verified payload with symbol keys.
-      def decode(raw_jws, config)
-        payload, = ::JWT.decode(raw_jws, public_key!(config), true,
+      def decode(raw_jws, provider)
+        payload, = ::JWT.decode(raw_jws, provider.public_key, true,
                                 algorithms: [Eddsa::NAME], verify_expiration: true, required_claims: REQUIRED_CLAIMS)
         payload.transform_keys(&:to_sym)
       rescue ::JWT::ExpiredSignature
@@ -59,30 +59,30 @@ module Kiosk
         raise Errors::Forbidden.new('KYC attestation signature invalid', hint: SIGNATURE_HINT)
       end
 
-      # Refused when this origin trusts no KYC issuer.
-      def public_key!(config)
-        key = config.kyc_public_key
-        return key unless key.nil?
+      # Refused when this origin trusts no KYC provider.
+      def provider!
+        provider = Kiosk.configuration.kyc_provider
+        return provider unless provider.nil?
 
         raise Errors::ModuleNotServed.new(
           'this operator does not serve the KYC module',
           hint: 'no KYC attestation is accepted at this origin; retrying will not help. ' \
-                'An operator that means to serve KYC sets Kiosk.configuration.kyc_public_key.'
+                'An operator that means to serve KYC sets Kiosk.configuration.kyc_provider.'
         )
       end
 
-      def check_issuer!(payload, config)
-        return if payload[:iss] == config.kyc_issuer
+      def check_issuer!(payload, provider)
+        return if payload[:iss] == provider.issuer
 
         raise Errors::Forbidden.new(
           'KYC attestation issuer mismatch',
-          hint: "expected #{config.kyc_issuer.inspect}, got #{payload[:iss].inspect}"
+          hint: "expected #{provider.issuer.inspect}, got #{payload[:iss].inspect}"
         )
       end
 
-      def audience_hint(payload, config)
-        "aud must equal this operator's kyc_audience " \
-          "(expected #{config.kyc_audience.inspect}, got #{payload[:aud].inspect})"
+      def audience_hint(payload, provider)
+        "aud must equal the audience this operator's KYC provider mints " \
+          "(expected #{provider.audience.inspect}, got #{payload[:aud].inspect})"
       end
 
       # Subject and level. A bigint-PK host's subject is an Integer.
@@ -93,14 +93,13 @@ module Kiosk
       end
 
       # The provider's own checks ({Kiosk::KycProviders::Base#accepts?}).
-      def check_provider!(payload, config)
-        provider = config.kyc_provider
-        return if provider.nil? || provider.accepts?(payload.transform_keys(&:to_s))
+      def check_provider!(payload, provider)
+        return if provider.accepts?(payload.transform_keys(&:to_s))
 
         raise Errors::Forbidden, 'the KYC provider does not accept this attestation at this operator'
       end
 
-      private_class_method :decode, :public_key!, :check_issuer!, :audience_hint, :check_subject!, :check_provider!
+      private_class_method :decode, :provider!, :check_issuer!, :audience_hint, :check_subject!, :check_provider!
     end
   end
 end

data/lib/kiosk/server/linked_assistants.rb

@@ -34,7 +34,7 @@ module Kiosk
 
         def settings_sql(assignments, bind_count)
           <<~SQL.squish
-            UPDATE #{Kiosk.configuration.schema}.agents
+            UPDATE #{Kiosk.configuration.schema}.kiosk_agents
             SET #{assignments.join(', ')}
             WHERE id = $#{bind_count - 2}
               AND user_id = $#{bind_count - 1}
@@ -47,18 +47,16 @@ module Kiosk
 
         def agents_sql
           <<~SQL.squish
-            SELECT id, public_key, created_at, human_label, spending_cap_cents, spending_cap_currency
-            FROM #{Kiosk.configuration.schema}.agents
+            SELECT id, public_key, bound_at, human_label, spending_cap_cents, spending_cap_currency
+            FROM #{Kiosk.configuration.schema}.kiosk_agents
             WHERE user_id = $1 AND issuer = $2 AND revoked_at IS NULL
             ORDER BY created_at
           SQL
         end
 
-        # `{ agent_id => { currency => cents } }`: the figure the spending cap
-        # counts, within `spending_cap_window_days` when set.
+        # `{ agent_id => { currency => cents } }`: what each agent spent.
         def spend_by_agent(user_id)
-          window_days = Kiosk.configuration.spending_cap_window_days&.to_i
-          tally(run(spend_sql(window_days), 'Kiosk assistant spend', [user_id, Kiosk.current_issuer, *window_days]))
+          tally(run(spend_sql, 'Kiosk assistant spend', [user_id, Kiosk.current_issuer]))
         rescue ::ActiveRecord::StatementInvalid => e
           raise unless missing_table?(e)
 
@@ -71,20 +69,27 @@ module Kiosk
           end
         end
 
-        # The day count, when set, is the third bind.
-        def spend_sql(window_days)
+        # One tally per currency.
+        def spend_sql
           schema = Kiosk.configuration.schema
-          window = window_days ? 'AND settlements.settled_at >= now() - make_interval(days => $3)' : ''
           <<~SQL.squish
-            SELECT settlements.agent_id, lower(btrim(settlements.currency)) AS currency,
-                   SUM(#{SettledSpend.net_cents_sql(schema)}) AS cents
-            FROM #{schema}.settlements
-            JOIN #{schema}.agents ON agents.id = settlements.agent_id
-            WHERE agents.user_id = $1 AND agents.issuer = $2 AND agents.revoked_at IS NULL #{window}
+            SELECT settlements.agent_id, lower(btrim(settlements.currency)) AS currency, SUM(#{net_cents_sql(schema)}) AS cents
+            FROM #{schema}.kiosk_settlements settlements
+            JOIN #{schema}.kiosk_agents agents ON agents.id = settlements.agent_id
+            WHERE agents.user_id = $1 AND agents.issuer = $2 AND agents.revoked_at IS NULL
             GROUP BY 1, 2 ORDER BY 2
           SQL
         end
 
+        # Each settlement less what was refunded of it, never below zero.
+        def net_cents_sql(schema)
+          <<~SQL.squish
+            GREATEST(settlements.settled_amount_cents - (
+              SELECT COALESCE(SUM(r.refunded_amount_cents), 0) FROM #{schema}.kiosk_refunds r WHERE r.settlement_id = settlements.id
+            ), 0)
+          SQL
+        end
+
         # By class name, so this file does not load `PG`.
         def missing_table?(error)
           error.cause&.class&.name == 'PG::UndefinedTable'
@@ -95,7 +100,7 @@ module Kiosk
           {
             agent_id: row.fetch('id'),
             fingerprint: fingerprint(row.fetch('public_key')),
-            created_at: row.fetch('created_at'),
+            bound_at: row.fetch('bound_at', nil),
             human_label: row.fetch('human_label', nil),
             spending_cap_cents: cap&.to_i,
             spending_cap_currency: row.fetch('spending_cap_currency', nil),

data/lib/kiosk/server/money.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # An amount in minor units (cents) as a person reads and types it: in the
+    # currency's major unit, with the ISO 4217 number of decimals.
+    module Money
+      # ISO 4217 currencies whose minor unit is not 1/100. Every other code has two decimals.
+      DECIMALS = {
+        'bif' => 0, 'clp' => 0, 'djf' => 0, 'gnf' => 0, 'isk' => 0, 'jpy' => 0, 'kmf' => 0,
+        'krw' => 0, 'pyg' => 0, 'rwf' => 0, 'ugx' => 0, 'uyi' => 0, 'vnd' => 0, 'vuv' => 0,
+        'xaf' => 0, 'xof' => 0, 'xpf' => 0,
+        'bhd' => 3, 'iqd' => 3, 'jod' => 3, 'kwd' => 3, 'lyd' => 3, 'omr' => 3, 'tnd' => 3,
+        'clf' => 4, 'uyw' => 4
+      }.freeze
+
+      module_function
+
+      # `5000, 'eur'` → `"50.00 EUR"`.
+      def format(cents, currency) = "#{amount(cents, currency)} #{currency.upcase}"
+
+      # `5000, 'eur'` → `"50.00"`.
+      def amount(cents, currency)
+        decimals = decimals(currency)
+        whole, fraction = cents.divmod(10**decimals)
+        decimals.zero? ? whole.to_s : "#{whole}.#{fraction.to_s.rjust(decimals, '0')}"
+      end
+
+      # `"50", 'eur'` → `5000`. Nil for text that is not an amount with at most the currency's decimals.
+      def parse(text, currency)
+        decimals = decimals(currency)
+        fraction = decimals.zero? ? '' : "(?:\\.(\\d{1,#{decimals}}))?"
+        match = /\A(\d+)#{fraction}\z/.match(text.strip) or return nil
+
+        (match[1].to_i * (10**decimals)) + match[2].to_s.ljust(decimals, '0').to_i
+      end
+
+      def decimals(currency) = DECIMALS.fetch(currency.downcase, 2)
+    end
+  end
+end

data/lib/kiosk/server/oauth_answers.rb

@@ -14,6 +14,7 @@ module Kiosk
       end
 
       def render_oauth_error(error)
+        error.response_headers.each { |name, value| response.set_header(name, value) }
         render_oauth(error.to_h, status: error.status)
       end
 

data/lib/kiosk/server/oauth_error.rb

@@ -24,6 +24,9 @@ module Kiosk
       # RFC 6749 Section 5.2: only a failed client authentication is a 401.
       def status = code == 'invalid_client' ? 401 : 400
 
+      # RFC 9110 Section 11.6.1: a 401 names its challenge, here the client assertion.
+      def response_headers = status == 401 ? { 'WWW-Authenticate' => Errors::ClientAssertionRefused.challenge } : {}
+
       def to_h = { error: code, error_description: message }
     end
   end

data/lib/kiosk/server/open_api.rb

@@ -41,7 +41,7 @@ module Kiosk
         served as `application/problem+json`; branch on its `code` member, not
         on the HTTP status alone.
 
-        `limit` and `cursor` are reserved parameter names this wire always
+        `limit` and `cursor` are reserved parameter names this protocol always
         accepts on a query. A query may declare `limit` to bound its page
         size; no verb declares `cursor`. The two names drive the cursor
         pagination of the specification's Section 8.4. A
@@ -58,14 +58,14 @@ module Kiosk
       }.freeze
 
       TAGS = [
-        { name: 'wire',    description: "The protocol's own reserved endpoints." },
+        { name: 'reserved', description: "The protocol's own reserved endpoints." },
         { name: 'queries', description: 'Reads. GET, arguments in the query string.' },
         { name: 'actions', description: 'Writes. POST, arguments in a JSON body.' }
       ].freeze
 
       def self.build(base_url:, config: Kiosk.configuration)
         endpoint = base_url.to_s.chomp('/') + config.mount_path
-        schemas, paths = Wire.surface(Array(config.capabilities).map(&:to_s))
+        schemas, paths = Reserved.surface(Array(config.capabilities).map(&:to_s))
         Verbs.add_entries(schemas, paths)
         document(endpoint, config, paths, schemas)
       end
@@ -79,7 +79,7 @@ module Kiosk
           security: [{ dpopAuth: [] }],
           tags: TAGS,
           paths: paths,
-          components: Wire.components(schemas)
+          components: Reserved.components(schemas)
         }
       end
       private_class_method :document
@@ -210,7 +210,7 @@ module Kiosk
             content: Refs.json_content("#{descriptor[:name]}.response")
           }
           ok[:headers] = Parameters::PAGINATION_HEADERS.keys.index_with { |h| { '$ref': "#/components/headers/#{h}" } } if kind == :query
-          { '200' => ok }.merge(Wire.problem_refs)
+          { '200' => ok }.merge(Reserved.problem_refs)
         end
 
         # A query's input is a component only when a parameter points into it.
@@ -282,7 +282,7 @@ module Kiosk
 
       # The protocol's own endpoints (§8.3, §11.3), declared rather than derived,
       # and the problem responses every operation shares.
-      module Wire
+      module Reserved
         SCHEMA_DESCRIPTION = "This origin's catalog: every query and action it publishes, " \
                              'with their descriptions and schemas. THE canonical surface ' \
                              'description — this OpenAPI document is derived from it. ' \
@@ -322,7 +322,7 @@ module Kiosk
         def schema_operation
           {
             operationId: 'schema',
-            tags: ['wire'],
+            tags: ['reserved'],
             description: SCHEMA_DESCRIPTION,
             # Public: opts out of the global `dpopAuth`.
             security: [],
@@ -333,7 +333,7 @@ module Kiosk
         def pay_operation
           {
             operationId: 'pay',
-            tags: ['wire'],
+            tags: ['reserved'],
             description: PAY_DESCRIPTION,
             requestBody: { required: true, content: Refs.json_content('pay.request') },
             responses: ok_responses('The settlement receipt.', 'pay.response')
@@ -371,7 +371,7 @@ module Kiosk
         PROBLEM = {
           type: 'object',
           title: 'Problem document (RFC 9457)',
-          description: 'Every error on this wire. Branch on `code`.',
+          description: 'Every error of this protocol. Branch on `code`.',
           properties: {
             type: {
               type: 'string', format: 'uri',

data/lib/kiosk/server/page.rb

@@ -4,7 +4,7 @@ module Kiosk
   module Server
     # What a query handler returns to paginate: this page's `rows`, an opaque
     # `next_cursor` (nil on the last page) and an optional `total` matching
-    # count. The wire sends the last two as `Link` and `X-Total-Count` headers.
+    # count. The protocol sends the last two as `Link` and `X-Total-Count` headers.
     Page = Data.define(:rows, :next_cursor, :total) do
       def initialize(rows:, next_cursor: nil, total: nil)
         if !next_cursor.nil? && next_cursor.to_s.empty?

data/lib/kiosk/server/payment_claim.rb

@@ -177,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
@@ -188,7 +188,7 @@ module Kiosk
       module AfterPayment
         # The executor calls this once, after it records the settlement of
         # `checkout_mandate`, so `c.after_payment` reads the row's `settlement`. A
-        # failure here never surfaces on the wire: the log carries it.
+        # 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)