kiosk-server 0.5.20 → 0.6.28

data/lib/kiosk/server/engine.rb

@@ -29,11 +29,11 @@ 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[
-        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,14 +144,18 @@ 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
 
       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`
@@ -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

@@ -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)
@@ -231,6 +231,27 @@ 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
+
+      # 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
@@ -273,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
@@ -103,16 +112,23 @@ 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)
-        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,18 +167,30 @@ 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.
+      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/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

@@ -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: a new pair can pay the checkout.
         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

@@ -3,98 +3,39 @@
 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 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. 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
+          return if cap.nil? || checkout_recorded?(checkout)
 
-          lock_assistant_payments!(identity.agent_id)
-          return if cart_recorded?(cart)
-
-          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}")
-        end
-
-        def refuse_over_cap!(cap, cart)
-          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
-
-          raise Errors::SpendingCapExceeded.new('assistant spending cap exceeded', hint: cap_hint(cap, spent, window_days, cart))
+                                                hint: "the cap is in #{cap_code.upcase}; this charge is in #{checkout.currency.upcase}")
         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)
-          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)
-          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}"
-        end
-
-        # 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
-
-        # Carts of this agent whose mandate is live, that 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
-            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)
-          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
-        end
+        def refuse_over_cap!(cap, checkout)
+          return if checkout.total_amount_cents <= cap
 
-        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?
+          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
 
-        # 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])
+        def checkout_recorded?(checkout)
+          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
       end
     end