kiosk-test-support 0.5.20 → 0.6.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82f1f47c2715da7a7ef6897038c156d7033991f159d7dea50446ee3af8933d01
-  data.tar.gz: 0b06db9324f1ea8d0e7e11036f756db6e4eef3fffc9899961506e95f0f999183
+  metadata.gz: c1a0b3e7ba79f9c1cf3f0e0ed29b2d9c7ed3deb87eed7deae9e030637d177903
+  data.tar.gz: 9df61c38d3daefdc760b862cdc84e071e049ee0753172dde44877585e9949161
 SHA512:
-  metadata.gz: 4b1c2beec651bb6bb2836c28cb5440903d113867d91f33bce3bdd42625c5d34336b0916332e39b3d92b60d5633668074decb3c5c2169597fd6c036c7b274595f
-  data.tar.gz: 66c9376f8e27a37bd455f503fa34f1617d8e7e790eb348fc44075494cc81e386f9e1ec23593a86f011781ec537909ec5a14a2feba01f7cb4fa4cee1684ccbbc9
+  metadata.gz: dc68223d652f7b3363e8368f1651a98b9c9bc3b52ef6f67e46edc752267348df2269790975a21dc9f72cd3066db4ebab33569b812b43ce66562fbfb3c0782f4e
+  data.tar.gz: 1e1d81c8ad29a55264b2d3b4e20a56ea6a27b7b90c0eff079680396158fb863c1f67dec1db3db7fc129edbed2c8191b06fd64bf21b5bb7d6dd0f81b1657eda02

data/CHANGELOG.md

@@ -12,6 +12,161 @@ already written is edited.
 
 ## [Unreleased]
 
+## [0.6.28] — 2026-10-26
+
+- 2026-10-26: Version 0.6.28, the tree cut that matches skill 0.6.28.
+
+## [0.6.27] — 2026-10-26
+
+- 2026-10-26: Version 0.6.27, the tree cut that matches skill 0.6.27.
+## [0.6.26] — 2026-10-26
+
+- 2026-10-26: Version 0.6.26, the tree cut that matches skill 0.6.26.
+## [0.6.25] — 2026-10-26
+
+- 2026-10-26: Version 0.6.25, the tree cut that matches skill 0.6.25.
+- 2026-10-26: The README DSL example seeds, then reads, and says that the assistant helpers call the default mount path `/kiosk`.
+
+## [0.6.24] — 2026-10-26
+
+- 2026-10-26: Version 0.6.24, the tree cut that matches skill 0.6.24.
+
+## [0.6.23] — 2026-10-26
+
+- 2026-10-26: Version 0.6.23, the tree cut that matches skill 0.6.23.
+
+## [0.6.22] — 2026-10-26
+
+- 2026-10-26: Version 0.6.22, the tree cut that matches skill 0.6.22.
+
+## [0.6.21] — 2026-10-26
+
+- 2026-10-26: Version 0.6.21, the tree cut that matches skill 0.6.21.
+
+## [0.6.20] — 2026-10-26
+
+- 2026-10-26: Version 0.6.20, the tree cut that matches skill 0.6.20.
+
+## [0.6.19] — 2026-10-26
+
+- 2026-10-26: Version 0.6.19, the tree cut that matches skill 0.6.19.
+
+## [0.6.18] — 2026-10-25
+
+- 2026-10-25: Version 0.6.18, the tree cut that matches skill 0.6.18.
+- 2026-10-25: The gem description and README say that the helpers solve proof-of-work tolls.
+
+## [0.6.17] — 2026-10-25
+
+- 2026-10-25: Version 0.6.17, the tree cut that matches skill 0.6.17.
+
+## [0.6.16] — 2026-10-25
+
+- 2026-10-25: Version 0.6.16, the tree cut that matches skill 0.6.16.
+- `SeededDatabase` empties every table on the search path but Rails' own two.
+
+## [0.6.15] — 2026-10-25
+
+- 2026-10-25: Version 0.6.15, the tree cut that matches skill 0.6.15.
+
+- 2026-10-25: `Kiosk::TestHelpers::SkillPin` (Minitest and RSpec): fails when kiosk-server gives a skill that `skill_sha256` is not the digest of, and tells how to make the new digest.
+
+## [0.6.14] — 2026-10-25
+
+- 2026-10-25: Version 0.6.14, the tree cut that matches skill 0.6.14.
+
+## [0.6.13] — 2026-10-25
+
+- 2026-10-25: Version 0.6.13, the tree cut that matches skill 0.6.13.
+
+## [0.6.12] — 2026-10-24
+
+- 2026-10-24: Version 0.6.12, the tree cut that matches skill 0.6.12.
+
+- 2026-10-24: The KYC stand-in replaces `c.kyc_provider` only, and keeps the audience of the provider it stands in for.
+
+## [0.6.11] — 2026-10-24
+
+- 2026-10-24: Version 0.6.11, the tree cut that matches skill 0.6.11.
+
+## [0.6.10] — 2026-10-23
+
+- 2026-10-23: Version 0.6.10, the tree cut that matches skill 0.6.10.
+
+## [0.6.9] — 2026-10-23
+
+- 2026-10-23: Version 0.6.9, the tree cut that matches skill 0.6.9.
+
+## [0.6.8] — 2026-10-22
+
+- 2026-10-22: Version 0.6.8, the tree cut that matches skill 0.6.8.
+
+## [0.6.7] — 2026-10-22
+
+- 2026-10-22: Version 0.6.7, the tree cut that matches skill 0.6.7.
+
+## [0.6.6] — 2026-10-22
+
+- 2026-10-22: Version 0.6.6, the tree cut that matches skill 0.6.6.
+
+## [0.6.5] — 2026-10-22
+
+- 2026-10-22: Version 0.6.5, the tree cut that matches skill 0.6.5.
+
+## [0.6.4] — 2026-10-22
+
+- 2026-10-22: Version 0.6.4, the tree cut that matches skill 0.6.4.
+
+## [0.6.3] — 2026-10-22
+
+- 2026-10-22: Version 0.6.3, the tree cut that matches skill 0.6.3.
+
+## [0.6.2] — 2026-10-22
+
+- 2026-10-22: Version 0.6.2, the tree cut that matches skill 0.6.2.
+
+## [0.6.1] — 2026-10-22
+
+- 2026-10-22: Version 0.6.1, the tree cut that matches skill 0.6.1.
+- 2026-10-21: Drops the `kiosk-pow-equihash` and `puma` dependencies; the host's bundle brings them. `Wire` names the gem to add, and refuses a toll in another proof of work.
+
+## [0.6.0] — 2026-10-21
+
+- 2026-10-21: The helpers make Ed25519 assistant keys and sign EdDSA; `Principal#key` replaces `#rsa_key`, and `Dpop.generate_key('ES256')` makes a P-256 key.
+- 2026-10-21: Version 0.6.0, the tree cut that matches skill 0.6.0.
+
+## [0.5.27] — 2026-10-21
+
+- 2026-10-21: `Assistant` registers at `/kiosk/oauth/register` and gets tokens by client assertion and DPoP; `login`, `proof_of_possession` and the challenge are gone.
+- 2026-10-21: Version 0.5.27, the tree cut that matches skill 0.5.27.
+
+## [0.5.26] — 2026-10-21
+
+- 2026-10-21: Version 0.5.26, the tree cut that matches skill 0.5.26.
+
+## [0.5.25] — 2026-10-21
+
+- 2026-10-21: Version 0.5.25, the tree cut that matches skill 0.5.25.
+
+## [0.5.24] — 2026-10-21
+
+- 2026-10-21: The gemspec depends on kiosk-server and kiosk-user-idp-devise, which the in-process helpers and `Person` require, so a bundle with this gem alone loads them.
+- 2026-10-21: Version 0.5.24, the tree cut that matches skill 0.5.24.
+
+## [0.5.23] — 2026-10-21
+
+- 2026-10-21: `Wire#dpop` replaces `Wire#bearer`: each call sends the token as `Authorization: DPoP` with a new proof. `Assistant#rotate` puts a new key on a principal.
+- 2026-10-21: Version 0.5.23, the tree cut that matches skill 0.5.23.
+
+## [0.5.22] — 2026-10-21
+
+- 2026-10-21: `Kiosk::TestHelpers::Mandate` signs the two AP2 v0.2 mandates; `Assistant#pay` and `Customer#pays` take a `checkout_jwt`.
+- 2026-10-21: Version 0.5.22, the tree cut that matches skill 0.5.22.
+
+## [0.5.21] — 2026-10-21
+
+- 2026-10-21: Version 0.5.21, the tree cut that matches skill 0.5.21.
+
 ## [0.5.20] — 2026-10-20
 
 - 2026-10-20: `InProcessOrigin` and `InProcessExecutor` call a verb through its route with a linked assistant's token; `InProcessWire` does the call.

data/README.md

@@ -4,52 +4,57 @@ Test helpers for [Kiosk](https://kiosk.tech) origins, and the journey-test DSL o
 
 ## What it does
 
-- `Kiosk::TestHelpers::Assistant` — registers, pays tolls, queries, runs actions, pays and listens for events against an origin, as an AI assistant does.
-- `Kiosk::TestHelpers::Wire` — the same transport without a principal: any method, any path, any headers.
+- `Kiosk::TestHelpers::Assistant` — registers, solves tolls, queries, runs actions, pays and listens for events against an origin, as an AI assistant does.
+- `Kiosk::TestHelpers::Wire` — the same transport without an assistant's credential: any method, any path, any headers.
 - `Kiosk::StoryTest` / `Kiosk::TestHelpers::Story` — a test told as a business story by customers' assistants and the people on the operator's site.
 - `Kiosk::TestHelpers::Kyc` — stands in for the operator's KYC provider, so a test decides how an identity check ends.
 - `Kiosk::TestHelpers::StripeMock` — starts a local stripe-mock that answers a confirmed charge as paid.
 - `Kiosk::TestHelpers::LiveServer` — serves the app over HTTP from the test process and gives the test an assistant for it.
 - `Kiosk::TestHelpers::SeededDatabase` — each test starts from the seeds and leaves the database empty.
 - `Kiosk::TestHelpers::DescriptorExamples` — the examples a served `/kiosk/schema` publishes, each checked against its schema.
+- `Kiosk::TestHelpers::SkillPin` — fails when an update of kiosk-server gives a skill that your `skill_sha256` is not the digest of.
 
 Carries the shared pieces of the Kiosk journey-test DSL: the `Journey` module mixed into RSpec / Minitest tests, the pluggable `executor` contract, a `NullExecutor` for self-tests, and the structured error classes that the framework-specific matchers and assertions look for.
 
 The journey DSL comes with one of the harnesses:
 
-> **Not on RubyGems yet** — so every `gem` line below carries `github: "kiosk-hq/kiosk"`, which is what makes it copy-pasteable today. Publication status and the canonical install are stated once, in the monorepo README's [Install](https://github.com/kiosk-hq/kiosk#install) section.
-
 ```ruby
 group :test do
-  gem "kiosk-rls-rspec", github: "kiosk-hq/kiosk"       # RSpec
+  gem "kiosk-rls-rspec"     # RSpec
   # or
-  gem "kiosk-rls-minitest", github: "kiosk-hq/kiosk"    # Minitest
+  gem "kiosk-rls-minitest"  # Minitest
 end
 ```
 
 Both harnesses pull `kiosk-test-support` as a transitive dependency.
 
+Your bundle brings what the helpers drive: `puma` for `LiveServer` (`rails new` writes it), and `kiosk-pow-equihash` for the solver that solves Equihash tolls. `Wire` solves no other proof of work.
+
 ## DSL
 
+Each `as_*` scope runs in a transaction that rolls back. `kiosk_seed` writes
+outside the scopes, so a test reads the rows that it seeds. With an `orders`
+table whose policy shows a customer only their own rows (kiosk-rls) and
+`c.enforce_db_role`:
+
 ```ruby
-as_agent_of(alice) do
-  run_action :create_order, items: ["bread"]
-end
+kiosk_seed :orders, owner: alice, item: "bread"
 
-as_user(alice) do
+as_agent_of(alice) do
   expect(query("select item from orders")).to contain_exactly({ item: "bread" })
 end
 
-as_anonymous do
-  expect { query("select * from orders") }.to be_rls_denied
+as_agent_of(bob) do
+  expect(query("select item from orders")).to be_empty
+  expect { query("insert into orders (user_id, item) values ('#{alice.id}', 'tea')") }.to be_rls_denied
 end
 ```
 
 Helpers: `as_agent_of(user, role:)`, `as_user(user, role:)`, `as_agent(name)`, `as_anonymous`, `query(sql)`, `run_query(name, **args)`, `run_action(name, **args)`, `pay_action(name, **args)`, `kiosk_seed(table, count:, owner:, **attrs)`. See the `Kiosk::TestHelpers::Journey` docstrings for full semantics.
 
-## Wiring an executor
+## Configuring an executor
 
-The DSL is inert until you wire an executor. In production-shaped tests you wire `Kiosk::TestHelpers::InProcessExecutor`, which runs against `kiosk-server` in your Rails app:
+The DSL is inert until you configure an executor. In production-shaped tests you configure `Kiosk::TestHelpers::InProcessExecutor`, which runs against `kiosk-server` in your Rails app:
 
 ```ruby
 # spec/spec_helper.rb (RSpec) or test/test_helper.rb (Minitest)
@@ -65,11 +70,11 @@ Kiosk::TestHelpers.executor = Kiosk::TestHelpers::NullExecutor.new.tap do |e|
 end
 ```
 
-The `NullExecutor` is the zero-dependency fallback for unit-shaped tests; production-shaped tests wire `Kiosk::TestHelpers::InProcessExecutor` (above).
+The `NullExecutor` is the zero-dependency fallback for unit-shaped tests; production-shaped tests configure `Kiosk::TestHelpers::InProcessExecutor` (above).
 
-## Driving the wire as an assistant
+## Driving the protocol as an assistant
 
-`Kiosk::TestHelpers::Assistant` registers, pays proof-of-work tolls, queries, runs, pays with signed mandates and listens on `<endpoint>/events`, against any origin — a test's own live server or a deployment:
+`Kiosk::TestHelpers::Assistant` registers its key as an OAuth client and gets DPoP-bound tokens, solves proof-of-work tolls, queries, runs, pays with closed AP2 mandates (SD-JWT) and listens on `/kiosk/events`. It calls the `/kiosk/...` paths, so it works against an origin that mounts the engine at the default path `/kiosk` — a test's own live server or a deployment. `Person` and the events client call the same paths:
 
 ```ruby
 require "kiosk/test_helpers/assistant"
@@ -81,7 +86,7 @@ events.subscribe("kyc_verification")
 assistant.run(rider, name: "reserve", scooter_code: "SK-001")
 ```
 
-Every answer carries its status, parsed body and headers. `Kiosk::TestHelpers::Wire` is the same transport without a principal: any method, any path, any headers.
+Every answer carries its status, parsed body and headers. `Kiosk::TestHelpers::Wire` is the same transport without an assistant's credential: any method, any path, any headers.
 
 ## Telling a business story
 
@@ -90,7 +95,7 @@ Every answer carries its status, parsed body and headers. `Kiosk::TestHelpers::W
 ```ruby
 class Shopper < Kiosk::TestHelpers::Customer
   def orders(*skus) = does(:create_order, items: skus.map { { sku: _1, qty: 1 } })
-  def pays_for(order) = pays(total: order["total_cents"], scope: "grocery", line_items: [{ order_id: order["order_id"] }])
+  def pays_for(order) = pays(order["checkout_jwt"])
 end
 
 class ShopStory < Kiosk::StoryTest
@@ -101,17 +106,17 @@ class ShopStory < Kiosk::StoryTest
 end
 ```
 
-- `a_customer(as:)` registers an assistant; `a_newcomer(as:)` holds a key and no account yet; `published(path)` reads what the origin shows anyone.
+- `a_customer(as:)` registers an assistant; `a_newcomer(as:)` registers a key and acts for no person yet; `published(path)` reads what the origin shows anyone.
 - `Customer#asks` and `#does` answer an `Answer` (`ok?`, `refused?(code)`, `detail`, `hint`, `rows`, `header`, `tolls_paid`, `solved_toll`, `next_page`); `asks(…, unpaid: true)` or `asks(…, proofs: […])` leaves the toll to the story.
-- `Kiosk::StoryTest#assert_refused(answer, code)` asserts the wire refused the `Answer` with `code`.
-- `Customer#sets_up_payment` and `#requests_verification` run the engine's `payment_setup` and `request_kyc`, and `#hears_verification_passed` waits for the outcome of the check it asked for last; `#pays(total:, scope:, line_items:, currency:)` signs the intent, cart and payment mandates for a quote and pays; on `payment_setup_required` it calls `payment_setup` and pays once more.
-- `Customer#account`, `#role` and `#claims` read its credential; `#signs_back_in`, `#with_a_fresh_credential`, `#redeems(link_code)`, `#asks_to_be_linked`, `#polls` and `#collects` are the sign-in and linking ceremonies.
+- `Kiosk::StoryTest#assert_refused(answer, code)` asserts the protocol refused the `Answer` with `code`.
+- `Customer#sets_up_payment` and `#requests_verification` run the engine's `payment_setup` and `request_kyc`, and `#hears_verification_passed` waits for the outcome of the check it asked for last; `#pays(checkout_jwt)` signs the two closed AP2 mandates for the checkout an action answered, unchanged, and pays; on `payment_setup_required` it calls `payment_setup` and pays once more.
+- `Customer#account`, `#role` and `#claims` read its credential; `#signs_back_in` and `#with_a_fresh_credential` ask the token endpoint for a new token; `#redeems(link_code)`, `#asks_to_be_linked`, `#polls` and `#collects` are the linking ceremonies.
 - `Customer#listens_for`, `#follows(*topics, subject:, since:)` and `#hears(topic, about:, on:, **data)` read the event stream, holding each heard payload to the schema the origin publishes for its topic.
 - `a_person(email:, password:)` signs a person in on the operator's site through `kiosk-user-idp-devise`'s `DeviseSession`: `links(customer)`, `link_code`, `approves(user_code)`, `unlinks(customer)`, `visits(path)`.
 
 ## Identity checks in tests
 
-A real identity check is a human showing documents to a provider; a test cannot do that, so `Kiosk::TestHelpers::Kyc` stands in for the operator's KYC provider for the length of each test and the test says how the check ends. The engine receives the provider's callback and runs the operator's code exactly as it would in production:
+A real identity check is a human showing documents to a KYC provider; a test cannot do that, so `Kiosk::TestHelpers::Kyc` stands in for the operator's KYC provider for the length of each test and the test says how the check ends. The engine receives the provider's callback and runs the operator's code exactly as it would in production:
 
 ```ruby
 require "kiosk/test_helpers/kyc"
@@ -128,13 +133,53 @@ class LicenceStory < Kiosk::StoryTest   # or an RSpec group including Kiosk::Tes
 end
 ```
 
-`kyc_attestation(principal, **attributes)` signs an attestation an assistant submits to `POST <endpoint>/agents/kyc`. A check the human refuses sends nothing, so there is no helper for it.
+`kyc_attestation(principal, **attributes)` signs an attestation an assistant submits to `POST /kiosk/agents/kyc`. A check the human refuses sends nothing, so there is no helper for it.
 
 `Kiosk::TestHelpers::StripeMock.start` fronts a local [stripe-mock](https://github.com/stripe/stripe-mock) that answers a confirmed charge as paid. stripe-mock lists a saved card for every Customer, so once `payment_setup` has mapped one, `pay` settles.
 
+## The skill pin
+
+kiosk-server gives the URL of the skill that AI assistants read, and each kiosk-server release gives the skill of its own version. You set `skill_sha256`, the SHA-256 of that file, in `config/initializers/kiosk.rb`. This command downloads the file from kiosk.tech and calculates the digest:
+
+```bash
+curl -fsS "$(bin/rails runner 'puts Kiosk.configuration.skill_url')" | shasum -a 256
+```
+
+```ruby
+c.skill_sha256 = "<the 64 hexadecimal characters that the command prints>"
+```
+
+Then add a test that names the skill version of that digest: `X.Y.Z` from `skill-vX.Y.Z.md`. Minitest:
+
+```ruby
+require "kiosk/test_helpers/skill_pin"
+
+class KioskSkillPinTest < ActiveSupport::TestCase
+  include Kiosk::TestHelpers::SkillPin::Assertions
+
+  test "skill_sha256 is the digest of the skill that kiosk-server gives" do
+    assert_kiosk_skill_pin hashed_version: "X.Y.Z"
+  end
+end
+```
+
+RSpec:
+
+```ruby
+require "kiosk/test_helpers/skill_pin/rspec"
+
+RSpec.describe "the skill pin" do
+  it "is the digest of the skill that kiosk-server gives" do
+    expect(Kiosk.configuration).to pin_the_served_skill(hashed_version: "X.Y.Z")
+  end
+end
+```
+
+After an update of kiosk-server to a release with a different skill, the test fails. Its message gives the URL of the new skill, the command that calculates its SHA-256, and the two lines to change. The test also fails when your configuration sets `skill_url`: kiosk-server gives it.
+
 ## Status
 
-Pre-v1.0 alpha. The Journey DSL surface is stable across pre-v1.0 minor bumps; the executor contract may still evolve pre-v1.0 (`Kiosk::TestHelpers::InProcessExecutor` implements it today).
+Pre-v1.0 alpha: the Journey DSL and the executor contract may change between releases. `Kiosk::TestHelpers::InProcessExecutor` implements the contract.
 
 ## License
 

data/lib/kiosk/story_test.rb

@@ -8,7 +8,7 @@ module Kiosk
   class StoryTest < ActiveSupport::TestCase
     include TestHelpers::Story
 
-    # Asserts the wire refused `response` with `code`.
+    # Asserts the protocol refused `response` with `code`.
     def assert_refused(response, code)
       assert response.refused?(code), "expected a #{code} refusal, got #{response}"
     end

data/lib/kiosk/test_helpers/assistant/events.rb

@@ -6,6 +6,7 @@ require 'openssl'
 require 'socket'
 require 'uri'
 require 'websocket/driver'
+require 'kiosk/test_helpers/dpop'
 
 module Kiosk
   module TestHelpers
@@ -35,14 +36,15 @@ module Kiosk
 
         attr_reader :url
 
-        def initialize(base_url:, token:, path: '/kiosk/events', timeout: 10)
-          uri  = URI(base_url)
-          tls  = uri.scheme == 'https'
-          @url = "#{tls ? 'wss' : 'ws'}://#{uri.host}:#{uri.port}#{path}"
-          @io  = open_socket(uri.hostname, uri.port, tls)
+        # `key` signs the DPoP proof of the upgrade; its `htu` is the events URL
+        # with the HTTP scheme, because the upgrade is an HTTP request there.
+        def initialize(base_url:, token:, key:, path: '/kiosk/events', timeout: 10)
+          http = URI.join(base_url, path)
+          @url = http.to_s.sub(/\Ahttp/, 'ws')
+          @io  = open_socket(http.hostname, http.port, http.scheme == 'https')
           @frames = []
           @closed = false
-          @driver = start_driver(token)
+          @driver = start_driver(Dpop.headers(token, key, method: 'GET', url: http.to_s))
           pump(timeout) { @frames.any? { it['type'] == 'welcome' } } || raise(Error, "#{@url} did not welcome the connection")
         end
 
@@ -98,9 +100,9 @@ module Kiosk
           ssl
         end
 
-        def start_driver(token)
+        def start_driver(headers)
           driver = WebSocket::Driver.client(self)
-          driver.set_header('Authorization', "Bearer #{token}")
+          headers.each { |name, value| driver.set_header(name, value) }
           driver.on(:message) { @frames << JSON.parse(it.data) }
           driver.on(:close)   { @closed = true }
           driver.on(:error)   { @closed = true }

data/lib/kiosk/test_helpers/assistant.rb

@@ -6,12 +6,14 @@ require 'securerandom'
 require 'uri'
 require 'jwt'
 require 'kiosk/test_helpers/wire'
+require 'kiosk/test_helpers/mandate'
 require 'kiosk/test_helpers/assistant/events'
 
 module Kiosk
   module TestHelpers
-    # An assistant on the wire: registers, then queries, runs and pays as the
-    # principal it registered, paying every proof-of-work toll it is asked for.
+    # An assistant over HTTP: registers its key as an OAuth client, then
+    # queries, runs and pays as the principal its token names, paying every
+    # proof-of-work toll it is asked for.
     #
     #   assistant = Kiosk::TestHelpers::Assistant.new(base_url: live_url)
     #   rider     = assistant.register!
@@ -19,8 +21,12 @@ module Kiosk
     class Assistant
       class RegistrationError < StandardError; end
 
-      # The account an assistant registered, and the key that signs its mandates.
-      Principal = Data.define(:agent_id, :user_id, :token, :rsa_key)
+      # The account an assistant acts for, its client_id (the agent_id), and
+      # the key that signs its client assertions, DPoP proofs and mandates.
+      Principal = Data.define(:agent_id, :user_id, :token, :key)
+
+      ASSERTION_TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+      DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code'
 
       attr_reader :wire
 
@@ -30,119 +36,133 @@ module Kiosk
 
       def base_url = wire.base_url
 
-      # `pow:` is `:solve`, `:skip` (send no proof) or a String sent verbatim as
-      # the proof; `wire_role:` puts a `role` the engine must ignore into the body.
-      def register_raw(pow: :solve, wire_role: nil)
-        register(pow:, wire_role:).first
+      # Registers `key` (RFC 7591). `pow:` is `:solve`, `:skip` (send no proof)
+      # or a String sent verbatim as the proof; `wire_role:` puts a `role` the
+      # engine must ignore into the body.
+      def register_raw(pow: :solve, wire_role: nil, key: Dpop.generate_key)
+        body = { jwks: jwks(key), token_endpoint_auth_method: 'private_key_jwt' }
+        body[:role] = wire_role if wire_role
+        case pow
+        when :solve then wire.post('/kiosk/oauth/register', body)
+        when :skip then unpaid.post('/kiosk/oauth/register', body)
+        else unpaid.post('/kiosk/oauth/register', body, 'Kiosk-PoW' => pow)
+        end
+      end
+
+      # A new key, registered: the principal has a client_id and no token yet.
+      def register_client!(pow: :solve)
+        key  = Dpop.generate_key
+        resp = register_raw(pow:, key:)
+        raise RegistrationError, "registration expected 201, got #{resp.status}: #{resp.body.inspect}" unless resp.status == 201
+
+        Principal.new(agent_id: resp.body.fetch('client_id'), user_id: nil, token: nil, key: key)
       end
 
-      def register!(pow: :solve)
-        response, key = register(pow:)
-        raise RegistrationError, "register! expected 201, got #{response.status}: #{response.body.inspect}" unless response.status == 201
+      # A new key, registered, holding its first token.
+      def register!(pow: :solve) = signed_in(register_client!(pow:))
 
-        Principal.new(agent_id: response.body.fetch('agent_id'), user_id: response.body.fetch('user_id'),
-                      token: response.body.fetch('access_token'), rsa_key: key)
+      # The principal holding a new token from the client_credentials grant.
+      def signed_in(principal)
+        response = token(principal)
+        raise RegistrationError, "token request expected 200, got #{response.status}: #{response.body.inspect}" unless response.status == 200
+
+        access_token = response.body.fetch('access_token')
+        principal.with(token: access_token, user_id: JWT.decode(access_token, nil, false).first['sub'])
       end
 
-      # The unauthenticated request that opens the account-binding ceremony (RFC 8628 §3.1).
-      def device_authorization(client_id:, public_key:, **extra)
-        wire.post_form('/kiosk/oauth/device_authorization',
-                       { 'client_id' => client_id, 'public_key' => public_key }.merge(extra.transform_keys(&:to_s)))
+      # Asks the token endpoint for a token of the principal's client (RFC 6749 §4.4).
+      def token(principal) = token_request(principal, 'grant_type' => 'client_credentials')
+
+      # Polls for the token a person grants on the operator's site (RFC 8628 §3.4).
+      def device_token(device_code, principal)
+        token_request(principal, 'grant_type' => DEVICE_CODE, 'device_code' => device_code)
+      end
+
+      # Opens the account-binding ceremony (RFC 8628 §3.1), with whatever else the caller sends.
+      def device_authorization(principal, **extra)
+        wire.post_form('/kiosk/oauth/device_authorization', assertion_params(principal).merge(extra.transform_keys(&:to_s)))
       end
 
       def kyc(principal, attestation_jws:)
-        wire.post('/kiosk/agents/kyc', { kyc_jws: attestation_jws }, wire.bearer(principal.token))
+        wire.post('/kiosk/agents/kyc', { kyc_jws: attestation_jws }, credential(principal))
       end
 
-      # `pay_tolls: false` answers a proof-of-work toll instead of paying it.
+      # `pay_tolls: false` answers a proof-of-work toll instead of solving it.
       def query(principal, name:, headers: {}, pay_tolls: true, **params)
-        (pay_tolls ? wire : unpaid).get("/kiosk/#{name}", params, wire.bearer(principal.token).merge(headers))
+        (pay_tolls ? wire : unpaid).get("/kiosk/#{name}", params, credential(principal).merge(headers))
       end
 
       def run(principal, name:, headers: {}, **args)
-        wire.post("/kiosk/#{name}", args, wire.bearer(principal.token).merge(headers))
+        wire.post("/kiosk/#{name}", args, credential(principal).merge(headers))
       end
 
-      # The intent and cart mandates for a quote of `total` cents, for #pay.
-      def mandates(principal, total:, scope:, line_items:, currency: 'eur')
-        now    = Time.now.to_i
-        common = { user_id: principal.user_id, agent_id: principal.agent_id, iss: base_url, currency:, iat: now, exp: now + 600 }
-        intent = common.merge(id: SecureRandom.uuid, scope:, cap_amount_cents: total)
-        { intent:, cart: common.merge(id: SecureRandom.uuid, intent_mandate_id: intent[:id], total_amount_cents: total, line_items:) }
-      end
-
-      def pay(principal, intent:, cart:, payment_method: 'pm_demo')
-        payment = payment_mandate(principal, cart:, payment_method:)
-        pay_raw(principal, intent_jws: sign_mandate(principal, intent), cart_jws: sign_mandate(principal, cart),
-                           payment_jws: sign_mandate(principal, payment))
+      # Signs the two closed AP2 mandates for `checkout_jwt`, unchanged, and pays.
+      def pay(principal, checkout_jwt, instrument: 'on_file')
+        pay_raw(principal, **Mandate.pay(principal.key, checkout_jwt, instrument:))
       end
 
       # On a 402 `payment_setup_required` it calls `payment_setup`, as the hint
       # asks, and sends the same mandates once more. Against stripe-mock the
       # Customer that `payment_setup` maps already lists a card, so that answer settles.
-      def pay_raw(principal, intent_jws:, cart_jws:, payment_jws:)
-        body   = { intent_mandate_jws: intent_jws, cart_mandate_jws: cart_jws, payment_mandate_jws: payment_jws }
-        answer = wire.post('/kiosk/pay', body, wire.bearer(principal.token))
+      def pay_raw(principal, checkout:, payment:)
+        body   = { checkout_mandate: checkout, payment_mandate: payment }
+        answer = wire.post('/kiosk/pay', body, credential(principal))
         return answer unless setup_required?(answer)
 
         run(principal, name: 'payment_setup')
-        wire.post('/kiosk/pay', body, wire.bearer(principal.token))
+        wire.post('/kiosk/pay', body, credential(principal))
       end
 
-      def payment_mandate(principal, cart:, payment_method: 'pm_demo')
-        cart = cart.transform_keys(&:to_sym)
-        now  = Time.now.to_i
-        { id: SecureRandom.uuid, cart_mandate_id: cart[:id], user_id: principal.user_id, agent_id: principal.agent_id,
-          iss: cart[:iss], payment_method:, amount_cents: cart[:total_amount_cents], currency: cart[:currency],
-          exp: now + 600, iat: now }
+      # Puts a new key on the principal's client (spec Section 5.7): the old
+      # key's assertion names the new key, and the new key signs its own. The
+      # answer's Principal holds the new key and a token bound to it.
+      def rotate(principal, new_key: Dpop.generate_key)
+        body = { client_assertion_type: ASSERTION_TYPE,
+                 client_assertion: client_assertion(principal, new_key: Dpop.thumbprint(new_key)),
+                 new_client_assertion: client_assertion(principal.with(key: new_key)), jwks: jwks(new_key) }
+        response = wire.post('/kiosk/auth/rotate', body)
+        return response unless response.status == 200
+
+        signed_in(principal.with(key: new_key))
       end
 
-      def sign_mandate(principal, payload) = JWT.encode(payload, principal.rsa_key, 'RS256')
-
-      # Signs in again with the key it holds.
-      def login(key) = wire.post('/kiosk/auth/login', possession(key))
-
-      # Redeems a link code a person minted on the operator's site.
-      def claim(code, key) = wire.post('/kiosk/auth/claim', { code: }.merge(possession(key)))
-
-      # Polls for the credential a person grants on the operator's site (RFC 8628 §3.4).
-      def device_token(device_code, key)
-        wire.post_form('/kiosk/oauth/token', 'grant_type' => 'urn:ietf:params:oauth:grant-type:device_code',
-                                             'device_code' => device_code, 'signed' => proof_of_possession(key))
-      end
+      # Redeems a link code a person minted on the operator's site; answers 204.
+      def claim(code, principal) = wire.post('/kiosk/auth/claim', { code:, **assertion_params(principal) })
 
-      # A proof that the assistant holds `key`, over a fresh challenge and bound to this origin.
-      def proof_of_possession(key)
-        _, challenge = wire.get_json('/kiosk/auth/challenge', public_key: key.public_key.to_pem)
-        JWT.encode({ aud: base_url, nonce: challenge['challenge'], jti: SecureRandom.uuid, iat: Time.now.to_i }, key, 'RS256')
+      # A client assertion (RFC 7523 §3) that the principal's key signs for this
+      # origin. `claims` adds or replaces members, such as the `new_key` of a rotation.
+      def client_assertion(principal, **claims)
+        payload = { iss: principal.agent_id, sub: principal.agent_id, aud: base_url, exp: Time.now.to_i + 60,
+                    jti: SecureRandom.uuid, **claims }
+        JWT.encode(payload, principal.key, Dpop.algorithm(principal.key))
       end
 
       # What the origin publishes about itself at `/kiosk/schema`.
       def schema = @schema ||= wire.get_json('/kiosk/schema').last
 
-      def events(principal) = Events.new(base_url:, token: principal.token).tap { (@connections ||= []) << it }
+      def events(principal) = Events.new(base_url:, token: principal.token, key: principal.key).tap { (@connections ||= []) << it }
 
       # Closes every event connection it opened.
       def disconnect = @connections&.each(&:close)
 
       private
 
-      def register(pow:, wire_role: nil)
-        key  = OpenSSL::PKey::RSA.generate(2048)
-        body = possession(key)
-        body[:role] = wire_role if wire_role
-        response = case pow
-                   when :solve then wire.post('/kiosk/auth/register', body)
-                   when :skip then unpaid.post('/kiosk/auth/register', body)
-                   else unpaid.post('/kiosk/auth/register', body, 'Kiosk-PoW' => pow)
-                   end
-        [response, key]
+      def jwks(key) = { keys: [Dpop.jwk(key)] }
+
+      def assertion_params(principal)
+        { 'client_assertion_type' => ASSERTION_TYPE, 'client_assertion' => client_assertion(principal) }
       end
 
-      def possession(key) = { public_key: key.public_key.to_pem, signed: proof_of_possession(key) }
+      # A token request carries a DPoP proof of the registered key, with no token yet.
+      def token_request(principal, form)
+        wire.post_form('/kiosk/oauth/token', form.merge(assertion_params(principal)), wire.dpop(nil, principal.key))
+      end
 
       def unpaid = Wire.new(base_url:)
 
+      # The principal's token and key, which the protocol signs a DPoP proof with.
+      def credential(principal) = wire.dpop(principal.token, principal.key)
+
       def setup_required?(answer)
         answer.status == 402 && answer.body.is_a?(Hash) && answer.body['code'] == 'payment_setup_required'
       end