kiosk-server 0.5.20 → 0.6.28

data/lib/generators/kiosk/install/templates/create_kiosk_mandates.rb.tt

@@ -1,21 +1,56 @@
 # frozen_string_literal: true
 
-# Migration 005 — kiosk AP2 mandate trail:
-# intent_mandates, cart_mandates, payment_mandates, settlements.
-# See the Payment (AP2 mandate chain) section of the spec.
+# The AP2 trail of a `pay`: the checkout mandate, the payment mandate and the
+# settlement. `reference` is the hash of the presented SD-JWT, unique per user.
+# A checkout has one live checkout mandate: `declined_at` records a charge
+# refused with no money moved, and frees the checkout.
 class CreateKioskMandates < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
-  def up
-    execute <<~'SQL'
-<%= ddl(:mandates, user_id_type: user_id_type) %>
-    SQL
-  end
+  def change
+    create_table <%= table :checkout_mandates %>, id: :uuid do |t|
+      t.text :reference, null: false
+      t.text :checkout_hash, null: false
+      t.column :user_id, <%= user_id_type %>, null: false
+      t.uuid :agent_id, null: false
+      t.text :issuer, null: false
+      t.jsonb :line_items, null: false
+      t.bigint :total_amount_cents, null: false
+      t.text :currency, null: false
+      t.timestamptz :expires_at, null: false
+      t.timestamptz :created_at, null: false, default: -> { 'now()' }
+      t.text :sd_jwt, null: false
+      t.timestamptz :declined_at
+      t.index %i[user_id reference], unique: true
+      t.index %i[user_id checkout_hash], unique: true, where: 'declined_at IS NULL'
+    end
+
+    create_table <%= table :payment_mandates %>, id: :uuid do |t|
+      t.text :reference, null: false
+      t.references :checkout_mandate, type: :uuid, null: false,
+                                      foreign_key: { to_table: <%= table :checkout_mandates %>, on_delete: :cascade }
+      t.column :user_id, <%= user_id_type %>, null: false
+      t.uuid :agent_id, null: false
+      t.text :issuer, null: false
+      t.text :payment_instrument, null: false
+      t.bigint :amount_cents, null: false
+      t.text :currency, null: false
+      t.timestamptz :expires_at
+      t.timestamptz :created_at, null: false, default: -> { 'now()' }
+      t.text :sd_jwt, null: false
+      t.index %i[user_id reference], unique: true
+    end
 
-  def down
-    # Reverse-FK order: payment_mandates and settlements both reference
-    # cart_mandates, so both drop before it; cart_mandates before intent_mandates.
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".payment_mandates)
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".settlements)
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".cart_mandates)
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".intent_mandates)
+    # The server writes a settlement; nobody signs it. One per checkout mandate.
+    create_table <%= table :settlements %>, id: :uuid do |t|
+      t.references :checkout_mandate, type: :uuid, null: false, index: { unique: true },
+                                      foreign_key: { to_table: <%= table :checkout_mandates %>, on_delete: :cascade }
+      t.column :user_id, <%= user_id_type %>, null: false, index: true
+      t.uuid :agent_id, null: false
+      t.text :issuer, null: false
+      t.text :psp_reference, null: false
+      t.bigint :settled_amount_cents, null: false
+      t.text :currency, null: false
+      t.text :network_confirmation_id
+      t.timestamptz :settled_at, null: false
+    end
   end
 end

data/lib/generators/kiosk/install/templates/create_kiosk_pow_spent.rb.tt

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 
-# Migration 008 — create kiosk.pow_spent.
-# The spent proof-of-work challenge ids, so a proof is accepted once across
-# every process and every deploy (PowSpentStores::ActiveRecord, the default).
+# The spent ids of proof-of-work challenges and client assertions. The primary
+# key accepts each id once, in every process and across deploys.
 class CreateKioskPowSpent < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
-  def up
-    execute <<~'SQL'
-<%= ddl(:pow_spent) %>
-    SQL
-  end
-
-  def down
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".pow_spent)
+  def change
+    create_table <%= table :pow_spent %>, id: :text do |t|
+      # The expiry sweep reads it.
+      t.timestamptz :expires_at, null: false, index: true
+    end
   end
 end

data/lib/generators/kiosk/install/templates/create_kiosk_refunds.rb.tt

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-# Migration 012 — create kiosk.refunds.
-# The refunds of settled charges (Kiosk::Server::PaymentClaim#refund), which
-# recent spend leaves out of the proof-of-work toll.
+# The refunds of settled charges, one row per PSP refund. Recent spend counts
+# a settlement less what was refunded of it.
 class CreateKioskRefunds < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
-  def up
-    execute <<~'SQL'
-<%= ddl(:refunds) %>
-    SQL
-  end
-
-  def down
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".refunds)
+  def change
+    create_table <%= table :refunds %>, id: :uuid do |t|
+      t.references :settlement, type: :uuid, null: false,
+                                foreign_key: { to_table: <%= table :settlements %>, on_delete: :cascade }
+      t.text :psp_reference, null: false, index: { unique: true }
+      t.bigint :refunded_amount_cents, null: false
+      t.timestamptz :refunded_at, null: false
+      t.check_constraint 'refunded_amount_cents > 0', name: 'kiosk_refunds_refunded_amount_cents'
+    end
   end
 end

data/lib/generators/kiosk/install/templates/create_kiosk_revocations.rb.tt

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 
-# Migration 009 — create kiosk.revocations.
-# Each agent's token revocation watermark, so a revoke or an unlink holds in
-# every process and across restarts (RevocationStores::ActiveRecord, the default).
+# Each agent's revocation watermark: a token issued before it stops verifying,
+# in every process and after a restart.
 class CreateKioskRevocations < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
-  def up
-    execute <<~'SQL'
-<%= ddl(:revocations) %>
-    SQL
-  end
-
-  def down
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".revocations)
+  def change
+    create_table <%= table :revocations %>, primary_key: :agent_id, id: :uuid, default: nil do |t|
+      t.timestamptz :revoked_before, null: false
+      t.foreign_key <%= table :agents %>, column: :agent_id, on_delete: :cascade
+    end
   end
 end

data/lib/generators/kiosk/install/templates/create_kiosk_visits.rb.tt

@@ -1,16 +1,15 @@
 # frozen_string_literal: true
 
-# Migration 011 — create kiosk.visits.
-# The visits the operator records as fulfilled (Kiosk::Visit.record!), which
-# lower the proof-of-work toll for a returning customer.
+# The visits the operator records as fulfilled (Kiosk::Visit.record!). Their
+# value lowers the proof-of-work toll for a returning customer.
 class CreateKioskVisits < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
-  def up
-    execute <<~'SQL'
-<%= ddl(:visits, user_id_type: user_id_type) %>
-    SQL
-  end
-
-  def down
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".visits)
+  def change
+    create_table <%= table :visits %>, id: :uuid do |t|
+      t.column :user_id, <%= user_id_type %>, null: false
+      t.bigint :value_cents, null: false
+      t.timestamptz :visited_at, null: false, default: -> { 'now()' }
+      t.check_constraint 'value_cents >= 0', name: 'kiosk_visits_value_cents'
+      t.index %i[user_id visited_at]
+    end
   end
 end

data/lib/generators/kiosk/install/templates/initializer.rb.tt

@@ -9,17 +9,21 @@ Kiosk.configure do |c|
   # Type of users.id: :uuid (default), :bigint, :integer or :text.
   c.user_id_type   = :<%= options[:user_id_type] %>
 
-  # coerce-then-validate on the per-verb wire is UNCONDITIONAL: arguments are
+  # coerce-then-validate on the per-verb endpoints is UNCONDITIONAL: arguments are
   # always checked against the verb's `input_schema` (§8.1). This flag adds a check:
   # it validates every answer against the verb's `output_schema`. Off in production,
   # where a descriptor typo would become a 500 for a caller.
   c.validate_responses = !Rails.env.production?
 
   # GUC namespace for SET LOCAL (and RLS policies). Default "app".
-  # c.guc_namespace = "<%= options[:guc_namespace] %>"
+  # c.guc_namespace = "app"
 
-  # Postgres schema for Kiosk helper functions and tables.
-  # c.schema = "<%= options[:schema] %>"
+  # Postgres schema of Kiosk's kiosk_* tables. Default "public".
+<% if public_schema? -%>
+  # c.schema = "public"
+<% else -%>
+  c.schema = "<%= options[:schema] %>"
+<% end -%>
 
   # Opt-in Postgres RLS: add `gem "kiosk-rls"` and create these database roles yourself.
   # c.app_role        = "app_role"      # runtime role with NOBYPASSRLS
@@ -42,6 +46,11 @@ Kiosk.configure do |c|
   # Owner block surfaced in /.well-known/kiosk.json.
   # c.owner = { name: "Your Company", support: "support@example.com" }
 
+  # The SHA-256 of the skill file that kiosk-server gives. Without it, discovery advertises no skill pin.
+  #   curl -fsS "$(bin/rails runner 'puts Kiosk.configuration.skill_url')" | shasum -a 256
+  # Kiosk::TestHelpers::SkillPin (kiosk-test-support) fails when an upgrade gives a different skill.
+  # c.skill_sha256 = "<the 64 hexadecimal characters that the command prints>"
+
   # Optional: an agent IdP of your own (subclass Kiosk::AgentIdentityProviders::Base; agent ids must be UUIDs).
   # c.agent_idp = MyExternalAgentIdp.new
 

data/lib/kiosk/payable.rb

@@ -4,8 +4,8 @@ require 'active_support/concern'
 
 module Kiosk
   # `include Kiosk::Payable` in the model that `Kiosk::Server::PaymentClaim`
-  # names. It gives the row its `payment_state`, the `cart` an assistant signs
-  # to pay for it, and the `settlement` that paid it.
+  # names. It gives the row its `payment_state`, the `checkout_jwt` an
+  # assistant's mandates bind to pay for it, and the `settlement` that paid it.
   module Payable
     extend ActiveSupport::Concern
 
@@ -22,25 +22,19 @@ module Kiosk
                    '`refunded`: the charge went back to the card.'
     }.freeze
 
-    # The `cart` member of the answer of an action that creates a payable row.
-    CART_SCHEMA = {
-      type: 'object', additionalProperties: false,
-      description: 'Sign the cart mandate with these three values, unchanged.',
-      properties: {
-        currency: { type: 'string' },
-        total_amount_cents: { type: 'integer' },
-        line_items: { type: 'array', items: { type: 'object' } }
-      },
-      required: %w[currency total_amount_cents line_items]
+    # The `checkout_jwt` member of the answer of an action that creates a payable row.
+    CHECKOUT_SCHEMA = {
+      type: 'string',
+      description: 'The checkout to pay, signed by this operator. Put it unchanged in your checkout mandate.'
     }.freeze
 
     class_methods do
       # Adds `settled_currency`, the currency of a settlement among `settlements`
-      # whose cart names the row, or NULL: the caller's own on the wire, all of
-      # them in a back office.
+      # whose checkout names the row, or NULL: the caller's own in the protocol, all
+      # of them in a back office.
       def with_settlement(settlements)
         select(arel_table[Arel.star],
-               Arel::Nodes::Grouping.new(settlements.joins(:cart_mandate).where(names_row).select(:currency)
+               Arel::Nodes::Grouping.new(settlements.joins(:checkout_mandate).where(names_row).select(:currency)
                                                     .limit(1).arel).as('settled_currency'))
       end
 
@@ -48,19 +42,19 @@ module Kiosk
 
       private
 
-      # `cart_mandates.line_items @> [{"<reference>": "<this row's id>"}]`.
+      # `checkout_mandates.line_items @> [{"<reference>": "<this row's id>"}]`.
       def names_row
         line = Arel::Nodes::NamedFunction.new(
           'jsonb_build_object', [Arel::Nodes.build_quoted(payment_claim.reference),
                                  Arel::Nodes::NamedFunction.new('CAST', [arel_table[:id].as(Arel.sql('text'))])]
         )
-        Arel::Nodes::InfixOperation.new('@>', Kiosk::CartMandate.arel_table[:line_items],
+        Arel::Nodes::InfixOperation.new('@>', Kiosk::CheckoutMandate.arel_table[:line_items],
                                         Arel::Nodes::NamedFunction.new('jsonb_build_array', [line]))
       end
     end
 
     # `pending` means a capture is in flight: the caller reads again and does
-    # not sign a new mandate. A row read without `with_settlement` asks the
+    # not sign new mandates. A row read without `with_settlement` asks the
     # settlements itself.
     def payment_state
       status = self[:payment_status]
@@ -71,16 +65,16 @@ module Kiosk
       UNPAID
     end
 
-    # The cart that pays for this row: a line naming the row, then `lines`,
-    # each `{qty:, price_cents:, ...}`, which sum to the total.
-    def cart(lines)
+    # The signed checkout that pays for this row, for its owner: a line naming
+    # the row, then `lines`, each `{qty:, price_cents:, ...}`, which sum to the total.
+    def checkout(lines)
       claim = self.class.payment_claim
-      { currency: claim.currency,
-        total_amount_cents: lines.sum { it[:qty] * it[:price_cents] },
-        line_items: [{ claim.reference => id }, *lines] }
+      Kiosk::Server::Checkout.sign(user_id: user_id, currency: claim.currency,
+                                   total_amount_cents: lines.sum { it[:qty] * it[:price_cents] },
+                                   line_items: [{ claim.reference => id }, *lines])
     end
 
-    # The first settlement whose cart names this row, or nil.
+    # The first settlement whose checkout names this row, or nil.
     def settlement = self.class.payment_claim.settlements(id).order(:created_at).first
 
     private

data/lib/kiosk/server/account_binding.rb

@@ -2,33 +2,28 @@
 
 module Kiosk
   module Server
-    # Binds a proven public key to a human's account. A fresh key gets a new
-    # linked agent row; a known key is rebound, keeping its agent_id and
-    # reputation and adopting the new holder's role.
+    # Binds a registered client to a human's account: the client keeps its
+    # agent_id and reputation and takes the role of its new holder. The first
+    # binding merges the assistant account into the human's account.
     module AccountBinding
       module_function
 
-      # Call only after possession of `public_key_pem` has been proven.
-      # `requested_role` always comes from a human's identity, never the wire.
+      # Call only after the client has authenticated.
+      # `requested_role` always comes from a human's identity, never the request.
       #
-      # @return [Hash] { agent_id:, user_id:, access_token:, fresh: }
-      def bind!(public_key_pem:, user_id:, requested_role: nil)
+      # @return [Client] the client under its new holder
+      def bind!(agent_id:, user_id:, requested_role: nil)
         config = Kiosk.configuration
-        pem    = public_key_pem.to_s.strip
         raise ArgumentError, 'user_id required' if user_id.nil? || user_id.to_s.empty?
 
+        client = Client.find(agent_id) || raise(ArgumentError, "no live client #{agent_id.inspect} at this origin")
         warn_role_resolution_not_total(config, requested_role)
-
-        # `lease_connection`: the operator's hooks must share this transaction.
-        conn = ::ActiveRecord::Base.lease_connection
-        existing = Rows.live_by_key(conn, config.schema, pem)
-        return rebind(conn, config, existing, user_id, requested_role) if existing
-
-        register_linked(conn, config, pem, user_id, requested_role)
+        rebind(::ActiveRecord::Base.lease_connection, config, client, user_id, requested_role)
+        Client.find(agent_id)
       end
 
       # Revokes `agent_id`'s binding, which must belong to `user_id`; its tokens
-      # stop verifying and its `/auth/login` is denied.
+      # stop verifying and the token endpoint refuses it.
       #
       # @raise [Errors::NotFound] when no live agent row matches the pair.
       def unlink!(agent_id:, user_id:)
@@ -59,27 +54,32 @@ module Kiosk
       class << self
         private
 
-        # Known key: remap the holder and role, keep agent_id and reputation.
+        # Remaps the holder and role, keeps agent_id and reputation.
         # The role is never read from the row: it belonged to the previous holder.
-        def rebind(conn, config, existing, user_id, requested_role = nil)
-          agent_id = existing.fetch('id')
-          previous = existing.fetch('user_id')
-          role     = resolved_role(config, requested_role)
+        def rebind(conn, config, client, user_id, requested_role)
+          role = resolved_role(config, requested_role)
           # The same holder still gets the role remap and revocation; only the hook is skipped.
-          transition = previous.to_s != user_id.to_s
+          transition = client.user_id.to_s != user_id.to_s
           conn.transaction do
-            Rows.rebind(conn, config.schema, agent_id, user_id, role)
-            claimed(config, agent_id, previous, user_id) if transition && config.assistant_claimed
+            Rows.rebind(conn, config.schema, client.id, user_id, role)
+            carry_reputation(client.user_id, user_id) if transition
+            claimed(config, client.id, client.user_id, user_id) if transition && config.assistant_claimed
           end
           # The old holder's tokens die (§6.3). The IdP dates new mints at the
-          # watermark, so the token minted below survives it.
-          revoke_tokens(config, agent_id)
-          { agent_id: agent_id, user_id: user_id.to_s, access_token: issue_token(agent_id, role), fresh: false }
+          # watermark, so a token minted after this survives it.
+          revoke_tokens(config, client.id)
+        end
+
+        # The new account adds the previous account's count of tolled calls,
+        # and the first binding merges the assistant account into it.
+        def carry_reputation(from, to)
+          TolledCalls.carry!(from:, to:)
+          AssistantAccounts.merge!(from:, into: to)
         end
 
-        # Next second: JWT `iat` is whole seconds and the check is `iat < watermark` (§6.3).
+        # §6.3: the tokens of the previous holder stop.
         def revoke_tokens(config, agent_id)
-          config.revocation_store.revoke_all(agent_id, at: Time.now.to_i + 1)
+          RevocationStores.revoke_issued(agent_id, store: config.revocation_store)
         end
 
         def claimed(config, agent_id, previous, user_id)
@@ -87,13 +87,6 @@ module Kiosk
           config.assistant_claimed.call(agent: agent_id, from: accounts.find(previous), to: accounts.find(user_id))
         end
 
-        # Fresh key: a new linked agent row under the approving human.
-        def register_linked(conn, config, pem, user_id, requested_role)
-          role = resolved_role(config, requested_role)
-          agent_id = conn.transaction { Rows.insert_linked(conn, config.schema, user_id, pem, role) }
-          { agent_id: agent_id, user_id: user_id.to_s, access_token: issue_token(agent_id, role), fresh: true }
-        end
-
         def not_linked
           Errors::NotFound.new(
             'no linked assistant account with this agent_id',
@@ -130,27 +123,15 @@ module Kiosk
           logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
           logger ? logger.warn(message) : Kernel.warn(message)
         end
-
-        def issue_token(agent_id, role)
-          AgentIdentityProviders::DefaultAgentIdp.new.issue(agent_id: agent_id, role: role)
-        end
       end
 
       # The agents-table statements a binding runs.
       module Rows
         module_function
 
-        def live_by_key(conn, schema, pem)
-          conn.exec_query(<<~SQL.squish, 'Kiosk agent lookup by key', [pem, Kiosk.current_issuer]).to_a.first
-            SELECT id, user_id FROM #{schema}.agents
-            WHERE public_key = $1 AND issuer = $2 AND revoked_at IS NULL
-            LIMIT 1
-          SQL
-        end
-
         def revoke_owned(conn, schema, agent_id, user_id)
           conn.exec_query(<<~SQL.squish, 'Kiosk agent unlink', [agent_id, user_id, Kiosk.current_issuer]).to_a.first
-            UPDATE #{schema}.agents
+            UPDATE #{schema}.kiosk_agents
             SET revoked_at = now()
             WHERE id = $1
               AND user_id = $2
@@ -165,22 +146,11 @@ module Kiosk
           role_set, role_binds =
             role ? [', allowed_roles = ARRAY[$3]::text[]', [role]] : [", allowed_roles = '{}'::text[]", []]
           conn.exec_query(<<~SQL.squish, 'Kiosk agent rebind', [user_id, agent_id, *role_binds])
-            UPDATE #{schema}.agents
-            SET user_id = $1#{role_set}
+            UPDATE #{schema}.kiosk_agents
+            SET user_id = $1, bound_at = now()#{role_set}
             WHERE id = $2
           SQL
         end
-
-        # The column is NOT NULL: no role is `'{}'`, never NULL.
-        def insert_linked(conn, schema, user_id, pem, role)
-          allowed_roles_sql, role_binds = role ? ['ARRAY[$4]::text[]', [role]] : ["'{}'::text[]", []]
-          rows = conn.exec_query(<<~SQL.squish, 'Kiosk linked agent insert', [user_id, pem, Kiosk.current_issuer, *role_binds])
-            INSERT INTO #{schema}.agents (user_id, allowed_roles, public_key, issuer)
-            VALUES ($1, #{allowed_roles_sql}, $2, $3)
-            RETURNING id
-          SQL
-          rows.to_a.first.fetch('id')
-        end
       end
       private_constant :Rows
     end

data/lib/kiosk/server/account_holder_gate.rb

@@ -4,7 +4,8 @@ module Kiosk
   module Server
     # Requires a human signed in through the operator's own session
     # (`user_idp`), never an agent token. A browser is sent to `sign_in_path`;
-    # any other caller gets a 401 naming where to sign in.
+    # any other caller gets a 401 with the `Kiosk-Session` challenge, naming
+    # where to sign in.
     module AccountHolderGate
       private
 
@@ -22,6 +23,7 @@ module Kiosk
           store_return_location
           redirect_to sign_in_path
         else
+          response.set_header('WWW-Authenticate', Errors::SessionRequired.challenge)
           render plain: sign_in_path ? "#{prompt} #{sign_in_directions(sign_in_path)}" : prompt,
                  status: :unauthorized
         end

data/lib/kiosk/server/agent_identity_providers/default_agent_idp.rb

@@ -5,14 +5,14 @@ require 'kiosk/agent_identity_providers/base'
 module Kiosk
   module Server
     module AgentIdentityProviders
-      # The bundled agent IdP: RS256 tokens signed with the origin's own key;
-      # payment keys from the agents table.
+      # The bundled agent IdP: EdDSA tokens signed with the origin's own key and
+      # bound to the agent's registered key (`cnf.jkt`); payment keys from the agents table.
       class DefaultAgentIdp < Kiosk::AgentIdentityProviders::Base
         def verify(request)
-          header = authorization_for(request)
-          return nil if header.blank?
+          token = Dpop.token(authorization_for(request))
+          return nil if token.nil?
 
-          claims = verified_claims(header.sub(/\ABearer\s+/i, ''))
+          claims = verified_claims(token)
           Kiosk::Identity.new(
             user_id: claims[:sub], role: claims[:role], actor: 'agent',
             agent_id: claims[:agent_id], claims: claims
@@ -22,7 +22,9 @@ module Kiosk
         end
 
         def issue(agent_id:, role:)
-          claims = { sub: lookup_user_id(agent_id), agent_id: agent_id, actor: 'agent' }
+          agent  = lookup_agent(agent_id)
+          claims = { sub: agent.fetch('user_id'), agent_id: agent_id, actor: 'agent',
+                     cnf: { jkt: AssistantKey.thumbprint(AssistantKey.from_pem(agent.fetch('public_key'))) } }
           claims[:role] = role.to_s unless role.nil? || role.to_s.empty?
           JwtIssuer.issue(
             claims: claims, audience: Kiosk.current_issuer, now: mint_instant(agent_id),
@@ -31,10 +33,10 @@ module Kiosk
         end
 
         def agent_payment_key(agent_id)
-          pem = agents_column('public_key', agent_id)&.fetch('public_key', nil)
+          pem = agent_row('public_key', agent_id)&.fetch('public_key', nil)
           raise Kiosk::AgentIdentityProviders::InvalidToken, "no key for agent #{agent_id}" if pem.nil?
 
-          OpenSSL::PKey::RSA.new(pem)
+          AssistantKey.from_pem(pem)
         end
 
         private
@@ -42,7 +44,7 @@ module Kiosk
         def verified_claims(token)
           JwtIssuer.verify(
             token: token,
-            jwks: Jwks.build(keys: [Kiosk.configuration.signing_key]),
+            jwks: Jwks.build(keys: Kiosk.configuration.signing_keys),
             audience: Kiosk.current_issuer,
             issuer: Kiosk.current_issuer
           )
@@ -58,18 +60,18 @@ module Kiosk
           Time.at(watermark).utc
         end
 
-        def lookup_user_id(agent_id)
-          row = agents_column('user_id', agent_id)
+        def lookup_agent(agent_id)
+          row = agent_row('user_id, public_key', agent_id)
           raise Kiosk::AgentIdentityProviders::InvalidToken, "unknown agent #{agent_id}" if row.nil?
 
-          row.fetch('user_id')
+          row
         end
 
-        # `column` is always a literal from this class, never caller input.
-        def agents_column(column, agent_id)
+        # `columns` is always a literal from this class, never caller input.
+        def agent_row(columns, agent_id)
           ::ActiveRecord::Base.lease_connection.exec_query(
-            "SELECT #{column} FROM #{schema}.agents WHERE id = $1 AND revoked_at IS NULL",
-            "Kiosk agent #{column}",
+            "SELECT #{columns} FROM #{schema}.kiosk_agents WHERE id = $1 AND revoked_at IS NULL",
+            "Kiosk agent #{columns}",
             [agent_id]
           ).to_a.first
         end

data/lib/kiosk/server/agent_rotation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Puts a new key on a registered client (spec Section 5.7). The registered
+    # key and the new key each sign a client assertion, and the assertion of
+    # the registered key names the new key, so the client keeps its id,
+    # account, role and reputation. Every earlier token is revoked.
+    module AgentRotation
+      NEW_KEY_HINT = 'the client assertion of your registered key carries `new_key`: the RFC 7638 ' \
+                     'thumbprint of the key in jwks, so the registered key names the key that replaces it'
+
+      SAME_CLIENT_HINT = 'sign both client assertions with your own client_id'
+
+      module_function
+
+      # @return [Client] the client with its new key
+      # @raise [ClientAssertion::Refused, Errors::BadRequest, Errors::Conflict]
+      def call(type:, assertion:, new_assertion:, jwks:)
+        new_key = AssistantKey.from_jwks(jwks)
+        client = prove_both!(type, assertion, new_assertion, new_key)
+        refuse_known_key!(new_key)
+        replace_key(client.id, AssistantKey.to_pem(new_key))
+        Client.find(client.id)
+      end
+
+      # Both assertions are verified, then both are spent, before any change.
+      def prove_both!(type, assertion, new_assertion, new_key)
+        old = ClientAssertion.verify(type, assertion)
+        new = ClientAssertion.verify(type, new_assertion, key: new_key)
+        refuse!('the client assertion does not name the new key', NEW_KEY_HINT) unless old.claims['new_key'] == AssistantKey.thumbprint(new_key)
+        refuse!('the two client assertions name two clients', SAME_CLIENT_HINT) unless new.client.id == old.client.id
+
+        [old, new].each { ClientAssertion.spend!(it) }
+        old.client
+      end
+
+      def refuse!(message, hint)
+        raise ClientAssertion::Refused.new(message, hint: hint)
+      end
+
+      def refuse_known_key!(key)
+        return unless Client.with_key(key)
+
+        raise Errors::Conflict.new('the new key is registered already',
+                                   hint: 'rotate to a key that this origin does not know')
+      end
+
+      # The key and the revocation watermark move together, so no token outlives the old key.
+      def replace_key(agent_id, pem)
+        conn = ::ActiveRecord::Base.lease_connection
+        conn.transaction do
+          conn.exec_query(<<~SQL.squish, 'Kiosk agent key rotation', [pem, agent_id])
+            UPDATE #{Kiosk.configuration.schema}.kiosk_agents SET public_key = $1 WHERE id = $2
+          SQL
+          RevocationStores.revoke_issued(agent_id)
+        end
+      end
+      private_class_method :prove_both!, :refuse!, :refuse_known_key!, :replace_key
+    end
+  end
+end

data/lib/kiosk/server/argument_decoder.rb

@@ -56,7 +56,7 @@ module Kiosk
         end
       end
 
-      # What a caller has to send for each string `format` the wire reads.
+      # What a caller has to send for each string `format` the protocol reads.
       FORMAT_SPELLINGS = {
         'date' => 'a calendar date as YYYY-MM-DD, e.g. 2026-08-19',
         'date-time' => 'an ISO 8601 timestamp, e.g. 2026-08-19T14:00:00Z'
@@ -76,7 +76,7 @@ module Kiosk
         "an object argument's leaves are SCALARS: `o%5Bk%5D=v`, not " \
         '`o%5Bk%5D%5B%5D=v`. Anything richer is an ACTION (POST).'
 
-      # The query string's shape: what Rack can decode and the wire accepts.
+      # The query string's shape: what Rack can decode and the protocol accepts.
       module QueryShape
         module_function