kiosk-server 0.5.20 → 0.6.1

data/lib/kiosk/server/device_code_grant.rb

@@ -2,13 +2,14 @@
 
 module Kiosk
   module Server
-    # The claim ceremony on the RFC 8628 device-grant wire: binds an agent key
-    # to an existing human account once the human approves.
+    # The claim ceremony on the RFC 8628 device-grant wire: binds a registered
+    # client to an existing human account once the human approves.
     #
-    #   .start    — POST /oauth/device_authorization
-    #   .exchange — POST /oauth/token (grant_type=device_code)
+    #   .start     — POST /oauth/device_authorization
+    #   .pay_toll! — POST /oauth/token (grant_type=device_code), before the client authenticates
+    #   .exchange  — POST /oauth/token (grant_type=device_code), after it authenticates
     module DeviceCodeGrant
-      GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code'
+      GRANT_TYPE = Client::DEVICE_CODE
 
       # Seconds; a faster poll gets `slow_down` (RFC 8628 §3.5).
       DEFAULT_POLL_INTERVAL = 5
@@ -18,9 +19,6 @@ module Kiosk
       @poll_registry = {}
       @poll_mutex    = Mutex.new
 
-      PROOF_REQUIRED = 'signed proof-of-possession required ' \
-                       '(GET /auth/challenge?public_key=… then sign {aud, nonce, jti})'
-
       STATUS_FAILURES = {
         pending: [:authorization_pending, 'the account holder has not yet approved'],
         denied: [:access_denied, 'the account holder denied the request'],
@@ -30,14 +28,13 @@ module Kiosk
 
       module_function
 
-      # No role parameter on purpose: the row takes the approving human's role.
-      def start(client_id:,
-                public_key_pem:,
+      # No role parameter on purpose: the client takes the approving human's role.
+      def start(client:,
                 store: Kiosk.configuration.device_authorization_store,
                 expires_in: DeviceAuthorization::DEFAULT_EXPIRES_IN,
                 now: Time.current)
         plain_device_code, plain_user_code, da = DeviceAuthorization.generate(
-          client_id: client_id, kind: :claim, public_key_pem: public_key_pem.to_s.strip,
+          client_id: client.id, kind: :claim, public_key_pem: client.public_key_pem,
           expires_in: expires_in, now: now
         )
         store.create(da)
@@ -45,26 +42,30 @@ module Kiosk
           expires_in: expires_in, interval: DEFAULT_POLL_INTERVAL, da: da }
       end
 
-      # Returns `{ok: true, access_token:, …}` or `{ok: false, error:, description:}`
-      # with an RFC 8628 §3.5 error code. The auth toll raises its own errors.
-      def exchange(device_code:, # rubocop:disable Metrics/ParameterLists -- the token controller and the specs pass these by name
-                   signed: nil,
-                   pow: nil,
+      # The first poll of each device code value pays the auth toll; 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)
+        config = Kiosk.configuration
+        paid   = "device_code:#{DeviceAuthorization.hash_device_code(device_code)}"
+        return if !AuthToll.on?(config) || config.pow_spent_store.spent?(paid)
+
+        AuthToll.gate(verb: 'oauth/token', body: { device_code: device_code.to_s }, pow: pow, config: config)
+        config.pow_spent_store.mark_spent(paid, now.to_i + DeviceAuthorization::DEFAULT_EXPIRES_IN)
+      end
+
+      # @return [Client] the client under the approving human's account
+      # @raise [OauthError] with an RFC 8628 §3.5 error code
+      def exchange(device_code:, client:,
                    store: Kiosk.configuration.device_authorization_store,
                    interval: DEFAULT_POLL_INTERVAL,
                    now: Time.current)
-        return failure(:invalid_request, 'device_code parameter required') if device_code.to_s.empty?
-
         hash = DeviceAuthorization.hash_device_code(device_code)
-        pay_toll_once!(device_code, hash, pow, now)
-        da = store.lookup_by_device_code_hash(hash)
-        return failure(:invalid_grant, 'unknown device_code') if da.nil?
-        return failure(:slow_down, 'polling faster than the advertised interval') if polled_too_fast?(hash, interval, now)
-
-        da = expire_if_due(da, store, now)
-        return bind_and_mint(authorization: da, signed: signed, store: store, now: now) if da.approved?
+        da = authorization_of(client, store.lookup_by_device_code_hash(hash))
+        fail!(:slow_down, 'polling faster than the advertised interval') if polled_too_fast?(hash, interval, now)
 
-        failure(*STATUS_FAILURES.fetch(da.status))
+        consume!(expire_if_due(da, store, now), store, now)
+        AccountBinding.bind!(agent_id: client.id, user_id: da.user_id, requested_role: da.requested_role)
       end
 
       def reset_poll_registry!
@@ -74,16 +75,11 @@ module Kiosk
       class << self
         private
 
-        # The first poll of each device code value pays the auth toll; 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_once!(device_code, hash, pow, now)
-          config = Kiosk.configuration
-          paid   = "device_code:#{hash}"
-          return if !AuthToll.on?(config) || config.pow_spent_store.spent?(paid)
+        # A claim row that this client opened; a row of another client is unknown to it.
+        def authorization_of(client, authorization)
+          return authorization if authorization&.claim? && authorization.client_id == client.id
 
-          AuthToll.gate(verb: 'oauth/token', body: { device_code: device_code.to_s }, pow: pow, config: config)
-          config.pow_spent_store.mark_spent(paid, now.to_i + DeviceAuthorization::DEFAULT_EXPIRES_IN)
+          fail!(:invalid_grant, 'unknown device_code')
         end
 
         def expire_if_due(authorization, store, now)
@@ -93,41 +89,14 @@ module Kiosk
           store.update(authorization.expire)
         end
 
-        # Possession of the row's key is proven before binding; a failed proof
-        # is `invalid_client` and leaves the row approved for a retry.
-        def bind_and_mint(authorization:, signed:, store:, now:)
-          refusal = possession_refusal(authorization.public_key_pem, signed)
-          return refusal if refusal
-          # Atomic, so two concurrent polls mint one token.
-          return failure(:invalid_grant, 'device_code already used') if store.claim_consume(authorization, now: now).nil?
-
-          token_response(authorization)
-        end
-
-        def possession_refusal(public_key_pem, signed)
-          return failure(:invalid_client, PROOF_REQUIRED) if signed.nil? || signed.to_s.empty?
-          return failure(:invalid_client, 'no public key bound to this authorization') if public_key_pem.blank?
-
-          payload = PopVerifier.verify!(public_key_pem: public_key_pem, signed: signed)
-          AuthChallenge.consume!(public_key_pem: public_key_pem, nonce: payload.fetch(:nonce))
-          nil
-        rescue Errors::Base => e
-          failure(:invalid_client, e.message)
-        end
-
-        def token_response(authorization)
-          role = authorization.requested_role
-          result = AccountBinding.bind!(public_key_pem: authorization.public_key_pem,
-                                        user_id: authorization.user_id, requested_role: role)
-          response = { ok: true, access_token: result[:access_token], token_type: 'Bearer',
-                       expires_in: Kiosk.configuration.access_token_ttl }
-          # RFC 6749 §5.1: the granted scope is the approving human's role.
-          response[:scope] = role if role
-          response
+        # Atomic, so two concurrent polls bind once.
+        def consume!(authorization, store, now)
+          fail!(*STATUS_FAILURES.fetch(authorization.status)) unless authorization.approved?
+          fail!(:invalid_grant, 'device_code already used') if store.claim_consume(authorization, now: now).nil?
         end
 
-        def failure(error, description)
-          { ok: false, error: error.to_s, description: description }
+        def fail!(error, description)
+          raise OauthError.new(error, description)
         end
 
         # Per process; a multi-process origin rate-limits at its edge.

data/lib/kiosk/server/dpop.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'digest'
+require 'jwt'
+require 'uri'
+
+module Kiosk
+  module Server
+    # RFC 9449 (spec Section 5.6): a token request, and a request that carries
+    # an access token, come with a proof that the registered key signed for
+    # this request. The proof's iat window is the replay bound; no nonce is
+    # issued and no jti is kept.
+    module Dpop
+      SCHEME = 'DPoP'
+      TYPE   = 'dpop+jwt'
+      WINDOW = 60
+      CLAIMS = %w[jti htm htu iat].freeze
+
+      # A proof that does not hold.
+      class Invalid < StandardError; end
+
+      module_function
+
+      # The `WWW-Authenticate` value of a 401 on a request that needs a token.
+      def challenge = %(#{SCHEME} algs="#{AssistantKey.algorithms.join(' ')}")
+
+      def hint
+        'send `Authorization: DPoP <access_token>` and one `DPoP` header: a JWS with typ dpop+jwt, ' \
+          "alg #{AssistantKey.algorithms.join(' or ')} and the public jwk of your registered key, signed by " \
+          'that key, whose payload carries jti, htm (the method), htu (the URL with no query), iat (now) ' \
+          'and ath (base64url SHA-256 of the access token)'
+      end
+
+      def token_request_hint
+        'send one `DPoP` header: a JWS with typ dpop+jwt, ' \
+          "alg #{AssistantKey.algorithms.join(' or ')} and the public jwk of your registered " \
+          'key, signed by that key, whose payload carries jti, htm POST, htu (the token URL) ' \
+          'and iat (now)'
+      end
+
+      # The access token of an `Authorization: DPoP <token>` header, else nil.
+      def token(authorization)
+        authorization.to_s[/\A#{SCHEME}\s+(\S+)\z/io, 1]
+      end
+
+      # Raises Errors::AccessTokenRefused unless `proof` is the key `jkt`'s proof
+      # for this method, URL and token, signed within {WINDOW} seconds of now.
+      def verify!(proof, token:, jkt:, method:, url:)
+        raise Invalid, 'the access token is bound to no key' if jkt.to_s.empty?
+
+        claims = check!(proof, jkt:, method:, url:, key: 'the key the token is bound to')
+        raise Invalid, 'the DPoP proof ath is not the hash of this token' unless claims['ath'] == hash_of(token)
+      rescue Invalid => e
+        raise Errors::AccessTokenRefused, e.message
+      end
+
+      # Raises OauthError `invalid_dpop_proof` unless `proof` is the proof of
+      # the registered key `jkt` for this token request. It carries no `ath`:
+      # there is no token yet.
+      def verify_token_request!(proof, jkt:, url:)
+        check!(proof, jkt:, method: 'POST', url:, key: 'your registered key')
+      rescue Invalid => e
+        raise OauthError.new(:invalid_dpop_proof, "#{e.message}: #{token_request_hint}")
+      end
+
+      # The base64url SHA-256 of the token: the `ath` a proof carries.
+      def hash_of(token) = Base64.urlsafe_encode64(Digest::SHA256.digest(token.to_s), padding: false)
+
+      # `key` names the key `jkt` is the thumbprint of.
+      def check!(proof, jkt:, method:, url:, key:)
+        raise Invalid, 'one DPoP header is required' if proof.to_s.empty? || proof.include?(',')
+
+        signer, claims = decode(proof)
+        raise Invalid, "the DPoP proof key is not #{key}" unless AssistantKey.thumbprint(signer) == jkt
+
+        check_request!(claims, method, url)
+        claims
+      end
+
+      def check_request!(claims, method, url)
+        raise Invalid, 'the DPoP proof htm is not this request method' unless claims['htm'] == method
+        raise Invalid, 'the DPoP proof htu is not this request URL' unless same_url?(claims['htu'], url)
+        raise Invalid, 'the DPoP proof iat is not within 60 seconds of now' unless (claims['iat'].to_i - Time.now.to_i).abs <= WINDOW
+      end
+
+      # The key is the proof's own `jwk`, and its type names the one algorithm.
+      def decode(proof)
+        key = header_key(::JWT.decode(proof, nil, false).last)
+        algorithm = AssistantKey.algorithm(key)
+        claims, = ::JWT.decode(proof, key, true, algorithms: [algorithm], required_claims: CLAIMS)
+        [key, claims]
+      rescue ::JWT::IncorrectAlgorithm
+        raise Invalid, "the DPoP proof alg is not #{algorithm}, the algorithm of its jwk"
+      rescue ::JWT::DecodeError
+        raise Invalid, 'the DPoP proof is not a JWS that its jwk signed, with the claims of RFC 9449'
+      end
+
+      def header_key(header)
+        raise Invalid, 'the DPoP proof typ is not dpop+jwt' unless header['typ'] == TYPE
+
+        jwk = header['jwk']
+        raise Invalid, 'the DPoP proof carries no public jwk' unless jwk.is_a?(Hash) && !jwk.keys.intersect?(AssistantKey::PRIVATE_MEMBERS)
+
+        AssistantKey.from_jwk(jwk)
+      rescue Errors::BadRequest => e
+        raise Invalid, "the DPoP proof jwk is refused: #{e.message}"
+      end
+
+      # Scheme and host without case, a default port dropped (RFC 9449 Section 4.3).
+      def same_url?(htu, url)
+        Kiosk::Configuration.normalize_origin(htu) == Kiosk::Configuration.normalize_origin(url) &&
+          URI.parse(htu.to_s).path == URI.parse(url).path
+      rescue URI::InvalidURIError
+        false
+      end
+
+      private_class_method :check!, :check_request!, :decode, :header_key, :same_url?
+    end
+  end
+end

data/lib/kiosk/server/eddsa.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'openssl'
+require_relative 'jwk'
+
+module Kiosk
+  module Server
+    # The JOSE algorithm EdDSA (RFC 8037) over the Ed25519 keys of OpenSSL.
+    # Loading this file registers `EdDSA` with ruby-jwt, so `JWT.encode` and
+    # `JWT.decode` accept the name.
+    class Eddsa
+      include ::JWT::JWA::SigningAlgorithm
+
+      NAME = 'EdDSA'
+
+      def initialize
+        @alg = NAME
+      end
+
+      def sign(data:, signing_key:)
+        raise_sign_error!("an EdDSA key is an Ed25519 key, got #{signing_key.class}") unless Jwk.ed25519?(signing_key)
+
+        signing_key.sign(nil, data)
+      end
+
+      def verify(data:, signature:, verification_key:)
+        raise_verify_error!("an EdDSA key is an Ed25519 key, got #{verification_key.class}") unless Jwk.ed25519?(verification_key)
+
+        verification_key.verify(nil, signature, data)
+      rescue OpenSSL::PKey::PKeyError
+        false
+      end
+
+      register_algorithm(new)
+    end
+  end
+end

data/lib/kiosk/server/engine.rb

@@ -32,8 +32,8 @@ module Kiosk
       # Credential-bearing wire fields, kept out of the `Parameters:` log line.
       # Whole-key matches, so an operator's own `promo_code` is left alone.
       FILTERED_PARAMETERS = %w[
-        signed code device_code kyc_jws
-        intent_mandate_jws cart_mandate_jws payment_mandate_jws
+        client_assertion new_client_assertion code device_code kyc_jws
+        checkout_mandate payment_mandate
       ].map { |field| /\A#{field}\z/ }.freeze
 
       initializer 'kiosk-server.filter_parameters' do |app|
@@ -61,7 +61,7 @@ module Kiosk
         ::Rails.logger ? ::Rails.logger.warn(message) : warn(message)
       end
 
-      # A wrong `issuer` refuses every proof with "proof audience mismatch".
+      # A wrong `issuer` refuses every client assertion with "client assertion audience mismatch".
       # Warned, not raised: an operator seeds before the public origin exists.
       LOOPBACK_ISSUER =
         %r{\A(?:https?://)?(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1\])(?::\d+)?/?\z}i
@@ -69,8 +69,8 @@ module Kiosk
       # The boot-time configuration checks. Each answers a message, or nil when the configuration is sound.
       module BootChecks
         ISSUER_UNSET =
-          '[kiosk-server] `c.issuer` is not set, so every authenticated request is refused ' \
-          'with "proof audience mismatch". Set it to the origin assistants dial: ' \
+          '[kiosk-server] `c.issuer` is not set, so every client assertion is refused ' \
+          'with "client assertion audience mismatch". Set it to the origin assistants dial: ' \
           'Kiosk.configure { |c| c.issuer = "https://api.example.com" }.'
 
         ISSUER_LOOPBACK =
@@ -144,9 +144,13 @@ module Kiosk
           get '/agents.txt',  to: 'kiosk/server/discovery#agents_txt'
           get '/agents.json', to: 'kiosk/server/discovery#agents_json'
           get '/auth.md',     to: 'kiosk/server/discovery#auth_md'
-          get '/.well-known/agent-configuration', to: 'kiosk/server/discovery#agent_configuration'
           get '/.well-known/kiosk.json',          to: 'kiosk/server/discovery#kiosk_json'
           get '/.well-known/api-catalog',         to: 'kiosk/server/discovery#api_catalog'
+          get '/.well-known/oauth-authorization-server', to: 'kiosk/server/discovery#oauth_authorization_server'
+          get '/.well-known/agent-skills/index.json',    to: 'kiosk/server/discovery#agent_skills_index'
+          get '/.well-known/ard.json',                   to: 'kiosk/server/discovery#ard'
+          get '/.well-known/ai-catalog.json',            to: 'kiosk/server/discovery#ard'
+          get '/.well-known/oauth-protected-resource',   to: 'kiosk/server/discovery#oauth_protected_resource'
         end
       end
 
@@ -165,10 +169,10 @@ module Kiosk
         # `events` is also in {HandlerMixin::RESERVED_NAMES}; keep the two in step.
         mount Kiosk::Server::EventsCable::RACK_APP => 'events', internal: true, anchor: true, as: :kiosk_events
 
-        get  'auth/challenge', to: 'auth#challenge'
-        post 'auth/register',  to: 'auth#register'
-        post 'auth/login',     to: 'auth#login'
-        post 'auth/revoke',    to: 'auth#revoke'
+        # RFC 7591 registration and the token endpoint (RFC 6749) are core.
+        post 'oauth/register', to: 'oauth_registration#create'
+        post 'oauth/token',    to: 'oauth_token#create'
+        post 'auth/rotate',    to: 'auth#rotate'
 
         # JWKS sits under the mount, not the origin root.
         get '.well-known/jwks.json', to: 'jwks#show'
@@ -183,7 +187,6 @@ module Kiosk
 
         # RFC 8628 device flow.
         post 'oauth/device_authorization', to: 'oauth_device_authorization#create'
-        post 'oauth/token',                to: 'oauth_token#create'
         get  'oauth/device/verify',        to: 'device_verify#show'
         post 'oauth/device/verify',        to: 'device_verify#create'
 

data/lib/kiosk/server/errors.rb

@@ -231,6 +231,13 @@ module Kiosk
         HTTP_STATUS = 401
       end
 
+      # The 401 of a request that needs an access token: it names the DPoP scheme (RFC 9449 §7.1).
+      class AccessTokenRefused < Unauthenticated
+        def initialize(message = 'a valid access token with its DPoP proof is required', hint: Dpop.hint) = super
+
+        def response_headers = { 'WWW-Authenticate' => Dpop.challenge }
+      end
+
       class Forbidden < Base
         CODE        = 'forbidden'
         HTTP_STATUS = 403

data/lib/kiosk/server/events_connection.rb

@@ -103,7 +103,7 @@ module Kiosk
 
       # Closes with `token_expired` or `revoked` once the credential no longer resolves (§8.5.6).
       def kiosk_credential_holds?
-        return true if resolve_identity
+        return true if token_holds?
 
         if kiosk_credential_expired?
           close(reason: 'token_expired', reconnect: true)
@@ -156,13 +156,23 @@ module Kiosk
         end
       end
 
+      # The token and the DPoP proof of the upgrade request.
+      def resolve_identity
+        under_issuer { Kiosk::Server::IdentityResolution.resolve(request) }
+      end
+
+      # §8.5.6: the proof was checked once, at the upgrade, and is past its
+      # 60-second window by now; a re-check reads the token alone.
+      def token_holds?
+        under_issuer { Kiosk::Server::IdentityResolution.agent_idp.verify(request) }
+      end
+
       # Under the upgrade's own issuer: this runs outside {IssuerMiddleware}.
       # A raising IdP refuses the upgrade rather than failing the socket.
-      def resolve_identity
-        issuer = Kiosk.configuration.issuer_for(request.base_url)
-        Kiosk.with_issuer(issuer) { Kiosk::Server::IdentityResolution.resolve(request) }
+      def under_issuer(&)
+        Kiosk.with_issuer(Kiosk.configuration.issuer_for(request.base_url), &)
       rescue StandardError => e
-        logger&.error("[kiosk] events connection identity resolution failed: #{e.class}")
+        logger&.error("[kiosk] events connection identity resolution failed: #{e.class}: #{e.message}")
         nil
       end
     end

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

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

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

@@ -8,50 +8,49 @@ module Kiosk
         private
 
         # A nil seam or a nil cap means uncapped. A cap allows no payment in
-        # another currency. Runs in the transaction that persists the cart,
-        # under a per-assistant lock, so two concurrent pays see each other: the
-        # second counts the first's cart as in flight. A cart already recorded
-        # is a repeat and adds nothing.
-        def enforce_spending_cap!(cart)
+        # 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.
+        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 cart_recorded?(cart)
+          return if checkout_recorded?(checkout)
 
-          refuse_other_currency!(cap.fetch(:currency), cart)
-          refuse_over_cap!(cap.fetch(:amount_cents).to_i, cart)
+          refuse_other_currency!(cap.fetch(:currency), checkout)
+          refuse_over_cap!(cap.fetch(:amount_cents).to_i, checkout)
         end
 
-        def refuse_other_currency!(cap_currency, cart)
+        def refuse_other_currency!(cap_currency, checkout)
           cap_code = MandateVerifier.canonical_currency(cap_currency)
-          cart_code = MandateVerifier.canonical_currency(cart.currency)
-          return if cap_code == cart_code
+          return if cap_code == checkout.currency
 
           raise Errors::SpendingCapExceeded.new('assistant spending cap is in another currency',
-                                                hint: "the cap is in #{cap_code.upcase}; this charge is in #{cart_code.upcase}")
+                                                hint: "the cap is in #{cap_code.upcase}; this charge is in #{checkout.currency.upcase}")
         end
 
-        def refuse_over_cap!(cap, cart)
+        def refuse_over_cap!(cap, checkout)
           window_days = Kiosk.configuration.spending_cap_window_days
-          spent = spent_in_window(cart, window_days)
-          return if spent + cart.total_amount_cents.to_i <= cap
+          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, cart))
+          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(cart, window_days)
-          binds = spent_binds(identity.agent_id, cart.currency, window_days)
+        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, cart)
+        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 #{cart.total_amount_cents.to_i}"
+            "this charge is #{checkout.total_amount_cents}"
         end
 
         # Settled cents for this agent in one currency (see SettledSpend),
@@ -67,16 +66,16 @@ module Kiosk
           SQL
         end
 
-        # Carts of this agent whose mandate is live, that have no settlement and
+        # 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}.cart_mandates c
+            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.cart_mandate_id = c.id)
+              AND NOT EXISTS (SELECT 1 FROM #{schema}.settlements s WHERE s.checkout_mandate_id = c.id)
           SQL
         end
 
@@ -86,9 +85,9 @@ module Kiosk
           window_days ? binds << window_days.to_i : binds
         end
 
-        def cart_recorded?(cart)
-          sql = "SELECT 1 FROM #{Kiosk.configuration.schema}.cart_mandates WHERE user_id = $1 AND mandate_id = $2"
-          connection.exec_query(sql, 'Kiosk cart recorded', [cart.user_id, cart.id]).any?
+        def checkout_recorded?(checkout)
+          sql = "SELECT 1 FROM #{Kiosk.configuration.schema}.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.