kiosk-server 0.5.20 → 0.6.28

data/README.md

@@ -8,28 +8,25 @@ The Kiosk Rails engine — host-side surface for [Kiosk](https://kiosk.tech).
 The full host-side surface is shipped and covered by the gem's own suite
 (`bundle exec rspec` in this directory runs it and prints how many examples that is):
 
-- **Wire-protocol controllers** — each verb route (`GET <mount>/<query-name>`, `POST <mount>/<action-name>`) reaches the operator's controller action that declares the verb, and `Kiosk::Handler` runs the wire's checks around it; `VerbController` refuses a verb route that no action answers; `WireController` serves the two reserved endpoints `GET <mount>/schema` and `POST <mount>/pay`; `VerbController` also serves `POST <mount>/payment_setup` against the payment provider port, and `PaymentSetupController` the page the provider returns the human to; `VerbController` serves `POST <mount>/request_kyc` against the KYC provider port, and `KycCallbackController` the provider's callback; `OpenApiController` serves a derived OpenAPI description of both at `GET <mount>/openapi.json`; `AuthController` runs the register/login proof-of-possession challenge-response (kiosk-pop — the auth story); JWKS backs stateless token verification.
-- **Account binding** — the claim/link ceremonies bind an agent's public key to an existing assistant-account holder's account: OAuth/RFC 8628-shaped device authorization + possession-proof-gated token poll, a session-authenticated verify page and «Link an assistant» page (minimal overridable engine views), link-code mint/redeem, and unlink. Tokens stay kiosk-pop-minted; the durable `DeviceAuthorizationStores::ActiveRecord` store (migration 004) is the default.
+- **Protocol controllers** — each operation's route (`GET <mount>/<query-name>`, `POST <mount>/<action-name>`) reaches the operator's controller action that declares the operation, and `Kiosk::Handler` runs the protocol's checks around it; `VerbController` refuses an operation's route that no action answers; `WireController` serves the two reserved paths `GET <mount>/schema` and `POST <mount>/pay`; `VerbController` also serves `POST <mount>/payment_setup` against the payment provider port, and `PaymentSetupController` the page the provider returns the human to; `VerbController` serves `POST <mount>/request_kyc` against the KYC provider port, and `KycCallbackController` the provider's callback; `OpenApiController` serves a derived OpenAPI description of both at `GET <mount>/openapi.json`; `OauthRegistrationController` registers an assistant's public key (RFC 7591) and `OauthTokenController` gives a registered client an access token for a client assertion (RFC 7523) and a DPoP proof (the `client_credentials` grant); `AuthController` puts a new key on a client; every access token is bound to the client's registered key, and a call that carries one also carries a DPoP proof (RFC 9449) that `IdentityResolution` checks; JWKS backs stateless token verification.
+- **Account binding** — the claim/link ceremonies bind a registered client to an existing assistant-account holder's account: the RFC 8628 device authorization and token poll, each authenticated by a client assertion, a session-authenticated verify page and «Link an assistant» page (minimal overridable engine views with no inline script or style, so a Content-Security-Policy of `default-src 'self'` holds), link-code mint/redeem, and unlink. The token endpoint gives the tokens; the durable `DeviceAuthorizationStores::ActiveRecord` store (the `create_kiosk_device_authorizations` migration) is the default.
 - **`Kiosk::Server::Executor`** — dispatches resolved commands to the host's registered queries and Actions.
-- **`Kiosk::Handler`** — the mixin an operator includes into a controller of their own to declare verbs as ordinary Rails actions; each declaration's `kind` says whether it is a query or an action, so one controller may declare both. The engine registers the controllers in `app/controllers/kiosk/` at boot and after every reload (see [Declaring queries and actions](#declaring-queries-and-actions)).
+- **`Kiosk::Handler`** — the mixin an operator includes into a controller of their own to declare operations as ordinary Rails actions; each declaration's `kind` says whether it is a query or an action, so one controller may declare both. The engine registers the controllers in `app/controllers/kiosk/` at boot and after every reload (see [Declaring queries and actions](#declaring-queries-and-actions)).
 - **`Kiosk::Server::PaymentClaim`** — the PSP decorator that keeps §11.6's operator half: one capture per payable row, and a paid state anchored to the capture (see [Payments](#payments)).
-- **Agent registration & login** — `AgentRegistration`, `AgentLogin`, `AuthToll`, and the pluggable agent-IdP resolve and mint per-agent identities.
-- **PoW gate** — `PowGate` enforces the reputation policy's N×PoW challenge-response (soft dependency on `kiosk-reputation`; zero overhead when no policy is set).
+- **Client registration and authentication** — `ClientRegistration`, `ClientAssertion`, `AssistantKey` (the one list of signing algorithms an assistant can use), `AuthToll`, and the pluggable agent-IdP resolve and mint per-agent identities.
+- **Proof-of-work toll** — `PowGate` asks the toll that the reputation policy sets, as N proof-of-work challenges (soft dependency on `kiosk-reputation`; zero overhead when no policy is set).
 - **`Kiosk::Server::WellKnown`** — pure-Ruby builder for `/.well-known/kiosk.json`.
 - **`Kiosk::Server::Headers`** + **`HeadersMiddleware`** — Rack middleware that injects `Kiosk-Server-Version`, `Kiosk-API-Version`, `Kiosk-Min-Client` on `/kiosk/*` responses.
 - **`IssuerMiddleware`** — answers `Kiosk.current_issuer` for each request: its origin when that is `c.issuer` or one of `c.additional_origins`, else `c.issuer`. Every origin served is its own operator.
-- **The audit sink** — `c.audit_sink` receives one `Kiosk::Server::ActionEvent` per action invocation, success and failure alike. The default is no sink, so no `ActionEvent` goes anywhere. The engine keeps its own state in the `kiosk` schema (agents, mandates, settlements, refunds, events, visits), but it writes no audit record there. See [The audit sink](#the-audit-sink).
-- **`Kiosk::Server::SchemaDefinitions`** — SQL generators for every table and helper that `bin/rails g kiosk:install` creates.
-- **`Kiosk::Server::Engine`** — the Rails engine: `kiosk` in `config/routes.rb` mounts it, drawing the full mount-prefixed PROTOCOL surface (the reserved wire, auth, JWKS, KYC, account binding), then one route per verb its block names — installs the root discovery routes when mounted, and auto-injects the headers and issuer middleware (see [Draw the routes](#draw-the-routes)).
-- **`Kiosk::Server::ConfigurationExtension`** — adds `mount_path`, `owner` (and the reputation/PoW slots) to `Kiosk::Configuration`.
+- **The audit sink** — `c.audit_sink` receives one `Kiosk::Server::ActionEvent` per action invocation, success and failure alike. The default is no sink, so no `ActionEvent` goes anywhere. The engine keeps its own state in its `kiosk_*` tables (agents, mandates, settlements, refunds, events, visits), but it writes no audit record there. See [The audit sink](#the-audit-sink).
+- **`Kiosk::Server::Engine`** — the Rails engine: `kiosk` in `config/routes.rb` mounts it, drawing the full mount-prefixed PROTOCOL surface (the reserved paths, auth, JWKS, KYC, account binding), then one route per operation its block names — installs the root discovery routes when mounted, and auto-injects the headers and issuer middleware (see [Draw the routes](#draw-the-routes)).
+- **`Kiosk::Server::ConfigurationExtension`** — adds `mount_path`, `owner` (and the reputation and proof-of-work settings) to `Kiosk::Configuration`.
 - **`bin/rails g kiosk:install`** — the install generator lays down the initializer, the migrations and the `kiosk` block in `config/routes.rb` that mounts the engine.
 
-kiosk-server is a Rails gem: it depends on railties, actionpack, actioncable, activerecord and activesupport (`~> 8.1`), and `require "kiosk/server"` loads them. Pieces such as `WellKnown` and `SchemaDefinitions` still work without a BOOTED Rails app — they just need the framework on the load path.
+kiosk-server is a Rails gem: it depends on railties, actionpack, actioncable, activerecord and activesupport (`~> 8.1`), and `require "kiosk/server"` loads them. `WellKnown` works without a BOOTED Rails app: it needs only the framework on the load path (see [The discovery document](#the-discovery-document-no-booted-rails-app-required)).
 
 ## Install
 
-> **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.
-
 ### Preconditions
 
 **Rails `~> 8.1`.** This gemspec pins `railties`, `actionpack`, `actioncable`,
@@ -38,23 +35,23 @@ that names a Rails gem is `kiosk-pay-stripe`, which pins `activerecord` at
 `~> 8.1`. **Rails 7.x and 8.0.x are excluded** — bundler refuses to resolve
 against an app on either, so for most "add Kiosk to an existing Rails app" this
 is the first thing to check, not a footnote. Older Rails lines are untested
-here, so they are not claimed; widening the floor means adding a CI leg first.
+here, so they are not claimed; widening the floor means adding a CI job first.
 
 **Ruby `>= 4.0`**, which every Kiosk gemspec declares and CI runs.
 
-**PostgreSQL.** The kiosk schema, the identity tables and the optional RLS
-backstop are Postgres; no other database is supported.
+**PostgreSQL.** Kiosk's `kiosk_*` tables and the optional RLS backstop are
+Postgres; no other database is supported.
 
 ### The line
 
 ```ruby
-gem "kiosk-server", github: "kiosk-hq/kiosk"
+gem "kiosk-server"
 ```
 
 Or, via the meta-gem:
 
 ```ruby
-gem "kiosk-all", github: "kiosk-hq/kiosk"
+gem "kiosk-all"
 ```
 
 ## Configure
@@ -72,11 +69,20 @@ Kiosk.configure do |c|
   c.roles         = %i[customer master support]
   # The default role. The engine refuses to boot when `c.roles` is set and
   # this is not one of them. An assistant admitted with no role of its own (a
-  # self-registration, or a binding whose approving human resolves none) gets
+  # registration, or a binding whose approving human resolves none) gets
   # this one. Name your least-privileged role. An origin that assigns roles to
   # nobody sets neither line, and then no token carries a `role` claim.
   c.registration_role = :customer
   c.owner         = { name: "Acme Inc.", support: "support@acme.example" }
+  # The SHA-256 of the skill file that kiosk-server gives (Kiosk.configuration.skill_url):
+  #   curl -fsS "$(bin/rails runner 'puts Kiosk.configuration.skill_url')" | shasum -a 256
+  # Without it, discovery advertises no skill pin. See "The skill pin" below.
+  c.skill_sha256  = "<the 64 hexadecimal characters that the command prints>"
+  # The Ed25519 key that signs access tokens, checkouts and receipts (EdDSA):
+  #   openssl genpkey -algorithm ed25519 | base64
+  c.signing_key   = Base64.decode64(ENV.fetch("KIOSK_SIGNING_KEY_B64"))
+  # An assistant key is an Ed25519 key. Add ES256 to also accept a P-256 key.
+  # c.assistant_algorithms = %w[EdDSA ES256]
   # c.mount_path  = "/kiosk"   # default
   # Optional: one event per action invocation. See "The audit sink".
   # c.audit_sink  = ->(event) { AuditRow.create!(**event.to_h) }
@@ -90,30 +96,34 @@ Set a KYC provider adapter (a `kiosk-kyc-*` gem) and the engine serves
 `kyc_verification` topic, and records the verified attributes against the
 person. Declare the attributes your gated actions need; gate with
 `Kiosk::Server::Kyc.require!`, which refuses `403 kyc_required` until the
-calling principal holds them. An action that needs only some of them passes
+calling customer holds them. An action that needs only some of them passes
 their names, `require!(%w[age_over_18])`, and may pass its own `detail:`.
 
 ```ruby
 Kiosk.configure do |c|
-  c.kyc_provider   = Kiosk::KycProviders::Prove.new(operator_id: "acme", intake_secret: ENV["PROVE_SECRET"])
-  c.kyc_claims     = %w[age_over_18]
-  c.kyc_issuer     = "https://kyc.example"   # the `iss` the provider signs
-  c.kyc_public_key = ENV["KYC_PUBLIC_KEY_PEM"]
-  c.kyc_audience   = "acme"                  # the `aud` it mints for you
+  c.kyc_claims   = %w[age_over_18]
+  c.kyc_provider = Kiosk::KycProviders::Proveli.new(operator_id: "acme",
+                                                    intake_secret: ENV.fetch("KIOSK_PROVELI_INTAKE_SECRET"),
+                                                    public_key: ENV.fetch("KIOSK_PROVELI_PUBLIC_KEY_PEM"))
 end
 ```
 
+The provider names the `iss` it signs, its Ed25519 public key and the `aud` it
+mints for you, and the engine checks every attestation against them. To accept
+attestations at `POST <mount>/agents/kyc` only, with no `request_kyc`, set
+`c.kyc_provider = Kiosk::KycProviders::Base.new(issuer:, public_key:, audience:)`.
+
 ### Payments
 
 Set a PSP adapter (a `kiosk-pay-*` gem) and the engine serves `pay`. Wrap it in
 `Kiosk::Server::PaymentClaim` and the engine keeps §11.6's operator half for you:
 it claims your payable row (`unpaid → paying`) before the capture, so a second
 `pay` for that row is refused before the processor is reached, and marks it
-`paid` when the capture returns. Under the claim it checks the signed cart:
-your currency, priced lines that sum to the total, and a total equal to your
-own price for the row. That price is the one thing you write — a checker that
-answers it from your catalog, given the row and the cart's item lines as
-signed, or returns a String saying why the cart is refused.
+`paid` when the capture returns. The checkout the assistant pays is one your
+origin signed, so under the claim the engine checks one thing: that its total
+is still your own price for the row. That price is the one thing you write — a
+checker that answers it from your catalog, given the row and the checkout's
+item lines, or returns a String saying why the checkout is refused.
 
 ```ruby
 module PriceChecker
@@ -124,8 +134,8 @@ Kiosk.configure do |c|
   c.payment_provider = Kiosk::Server::PaymentClaim.new(
     psp, currency: "eur", model: "Order", reference: "order_id", query: "my_orders"
   )
-  c.cart_price_checker = PriceChecker
-  c.after_payment      = ->(order_id) { CourierDispatchJob.arm!(order_id) } # optional
+  c.checkout_price_checker = PriceChecker
+  c.after_payment          = ->(order_id) { CourierDispatchJob.arm!(order_id) } # optional
 end
 ```
 
@@ -136,46 +146,69 @@ whose unpaid value is `unpaid`.
 The model also includes `Kiosk::Payable`, which gives each row:
 
 - `payment_state`: `unpaid`, `pending` while a capture is in flight, `paid`, or
-  `refunded`. Your per-user query publishes it, so a capture in flight never
+  `refunded`. Your query of the customer's own rows publishes it, so a capture in flight never
   reads as *not paid*. `Order.own.with_settlement(Kiosk::Settlement.own)` reads
   it for many rows in one query.
-- `cart(lines)`: the cart your action returns for the assistant to sign, a line
-  that names the row and then your priced lines.
-- `settlement`: the receipt of the capture that paid the row. `c.after_payment`
-  runs once this receipt is recorded, so it can refund against it.
+- `checkout(lines)`: the `checkout_jwt` your action returns, which the
+  assistant's AP2 mandates bind. Your origin signs it EdDSA with
+  `c.signing_key`, for the row's owner, with a random `jti`. Its first line names the row; then your
+  priced lines.
+- `settlement`: the record of the capture that paid the row. `c.after_payment`
+  runs once this record is written, so it can refund against it.
 
 When the capture returns, the engine pushes `{"order_id": "…", "payment_state":
 "paid"}` to the row's owner on the `payment` topic. Refund through the claim,
 `refund(psp_reference:, amount_cents:, key:)`: `key` names this refund among
 the refunds of the charge, so a retry with the same key refunds once. It
-records the refund in `kiosk.refunds`, and recent spend leaves the refunded
-cents out. The spending cap gets the refunded amount back. When the refund
-returns the whole charge, set the row's status column to `refunded`, which is
-where `payment_state` reads it. Then call `announce(id, "refunded")` on the
+records the refund in `kiosk_refunds`, and recent spend leaves the refunded
+cents out. When the refund returns the whole charge, set the row's status
+column to `refunded`, which is where `payment_state` reads it. Then call `announce(id, "refunded")` on the
 claim to push the same topic.
 
-A repeat of a chain whose capture did not complete runs the capture again under
-the same key, the cart mandate id, so your PSP adapter must key its charge by
-it (`kiosk-pay-stripe` does). A charge refused with no money moved marks the
-cart declined: it stops counting against `spending_cap` at once, and a repeat of
-that chain answers `409 conflict`.
-
-Set `c.spending_cap = Kiosk::Server::ColumnSpendingCap.new` to cap what each
-assistant spends. The human sets the cap on `/kiosk/auth/assistants`: an amount
-in cents and a currency. The engine refuses a `pay` that passes the cap, or a
-`pay` in another currency, with `403 spending_cap_exceeded` before the capture.
+A repeat of mandates whose capture did not complete runs the capture again
+under the same key, the checkout mandate's `reference`, so your PSP adapter must
+key its charge by it (`kiosk-pay-stripe` does). One checkout holds one live
+checkout mandate: a second pair for it answers `409 conflict`. A charge refused
+with no money moved marks the checkout mandate declined: a repeat of that pair
+answers `409 conflict`, and a new pair for the same checkout is accepted.
+
+A settled `pay` answers the settlement and the two AP2 receipts,
+`checkout_receipt` and `payment_receipt`, which your origin signs EdDSA with
+`c.signing_key`. The payment receipt carries the card network's id of the charge
+that your PSP adapter's `capture` answers as `network_confirmation_id`. When the
+adapter answers none, the receipt carries `not reported by the payment provider`.
+
+Set `c.spending_cap = Kiosk::Server::ColumnSpendingCap.new` to cap what one
+payment of each assistant may charge. The human sets the cap on
+`/kiosk/auth/assistants`: an amount and a currency. The engine refuses a `pay`
+whose checkout total is above the cap, or whose checkout is in another
+currency, with `403 spending_cap_exceeded` before the capture. A cap of 0
+stops the payments of that assistant.
 
 ### Proof of work
 
-Set a policy and the engine tolls the first call of each access token; the
-token then calls freely until it expires (`access_token_ttl`, 3600 seconds by
-default). With the ready-made policy, the more the customer spent here, the
-smaller the chance that a session pays the toll:
+The toll needs two gems beside kiosk-server: `kiosk-reputation`, which holds
+the policies and the challenges, and `kiosk-pow-equihash`, the proof-of-work
+backend. Add both to your Gemfile and `require` them. Both tolls sign their
+challenges with `c.pow_secret`.
+
+**The call toll.** Set a policy and the engine asks it on each query, action
+and `pay`. The engine counts each account's tolled calls since its last proof.
+The assistants bound to one account share that count, and a new access token or
+a key rotation keeps it. A binding adds the count of the assistant's previous
+account to the count of its new account. With the ready-made policy, an account
+solves a proof on every 10th call, and the more its customer spent here, the
+more calls pass between two proofs.
+
+**The registration toll.** `c.registration_pow_count` is the number of proofs
+that a client registration, a link-code claim and the first token poll of each
+device code cost. The default is 0, which asks for none.
 
 ```ruby
 Kiosk.configure do |c|
-  c.pow_secret        = ENV.fetch("KIOSK_POW_SECRET")
-  c.reputation_policy = Kiosk::Reputation::Policies::RecentSpend.new(within: 1.week, cap: 100)
+  c.pow_secret             = ENV.fetch("KIOSK_POW_SECRET")
+  c.reputation_policy      = Kiosk::Reputation::Policies::RecentSpend.new(within: 1.week, cap: 100)
+  c.registration_pow_count = 1
 end
 ```
 
@@ -186,23 +219,40 @@ you honour a booking that takes no payment:
 Kiosk::Visit.record!(user_id: booking.user_id, value_cents: 45_00)
 ```
 
+### Change the signing key
+
+`c.signing_key` signs every access token, checkout and receipt. To change it with no
+break, set the new key as `c.signing_key` and the old one as
+`c.previous_signing_key` (a public PEM is enough). The JWKS then publishes
+both, and a token or checkout that either key signed verifies. Remove
+`c.previous_signing_key` after one access-token lifetime, when no checkout that
+the old key signed is still to be paid.
+
+```ruby
+c.signing_key          = Base64.decode64(ENV.fetch("KIOSK_SIGNING_KEY_B64"))
+c.previous_signing_key = Base64.decode64(ENV.fetch("KIOSK_PREVIOUS_SIGNING_KEY_B64"))
+```
+
 
 ## Upgrading
 
-### The schema
+### The tables
 
 `rails generate kiosk:install` emits the **genesis** — the whole current shape,
-as migrations. That is the fresh-install path. Migrations already in
+as migrations. That is the fresh-install path. The migrations create Kiosk's
+tables as `kiosk_*` tables in the schema `--schema` names, `public` by default;
+`c.schema` names the same schema at run time. From 1.0, migrations already in
 `db/migrate/` are never re-emitted and never edited: a change to the Kiosk
-schema arrives as a new file you copy in and migrate, so `db:migrate` on your
-existing database transfers only what it has not run.
+tables arrives as a new file you copy in and migrate, so `db:migrate` on your
+existing database transfers only what it has not run. Before 1.0 a release may
+replace the genesis; its changelog entry says so.
 
 Each MAJOR publishes its own genesis and drops the previous major's chain, so
 **an upgrade crossing a major stops at it.** Install that major, `bin/rails
 db:migrate`, then move on — one major at a time. A fresh install at any major
 gets that major's genesis and replays no history at all.
 
-MINOR and PATCH releases only ever add files to the chain.
+From 1.0, MINOR and PATCH releases only ever add files to the chain.
 
 ### The configuration
 
@@ -225,13 +275,24 @@ The principle behind all three: generate as little as possible, derive at boot
 whatever can be derived, default whatever can be defaulted, and fail closed on
 what can be neither.
 
+### The skill pin
+
+Each kiosk-server release gives the skill of its own version as
+`skill_url`. Do not set `skill_url`. After an upgrade to a release with a
+different skill, your `skill_sha256` is the digest of the old file, and an AI
+assistant that checks the digest refuses the skill. The skill pin test of
+`kiosk-test-support` (`Kiosk::TestHelpers::SkillPin`) fails in this case, and
+its message tells you how to make the new digest.
+
 
 ## Multi-process deployments
 
-The PoW gate keeps spent challenge ids in `c.pow_spent_store`, by default
-`Kiosk::Server::PowSpentStores::ActiveRecord`: the `kiosk.pow_spent` table that
+The toll keeps spent challenge ids in `c.pow_spent_store`, by default
+`Kiosk::Server::PowSpentStores::ActiveRecord`: the `kiosk_pow_spent` table that
 `bin/rails g kiosk:install` lays down. Every process and every deploy shares it,
-so a proof is accepted once (kiosk.tech `protocol.md` §15.2).
+so a proof is accepted once (kiosk.tech `protocol.md` §15.2). The token
+endpoint keeps the `jti` of each client assertion in the same store, so an
+assertion is accepted once too.
 
 Any other backend works: the contract is `claim(id, exp) → Boolean`,
 `release(id)`, `spent?(id)`, `mark_spent(id, exp)`, and `claim` **MUST** be one
@@ -239,24 +300,15 @@ atomic operation (Redis `SET … NX EX`, or SQL `INSERT … ON CONFLICT`). A
 read-then-write reintroduces exactly the replay race the gate closes.
 
 Token revocation lives in `c.revocation_store`, by default
-`Kiosk::Server::RevocationStores::ActiveRecord`: the `kiosk.revocations` table,
-which `bin/rails g kiosk:install` lays down too. A revoke, a rebind or an unlink
+`Kiosk::Server::RevocationStores::ActiveRecord`: the `kiosk_revocations` table,
+which `bin/rails g kiosk:install` lays down too. A key rotation, a rebind or an unlink
 stops the agent's older tokens in every process and after a restart, and a
 token of an unlinked agent stops at once. The contract is
 `revoke_all(agent_id, at:)`, `watermark_for(agent_id)` and
 `revoked?(agent_id:, iat:)`.
 
-Outstanding auth challenges live in `c.auth_challenge_store`, by default
-`Kiosk::Server::AuthChallengeStores::ActiveRecord`: the `kiosk.auth_challenges`
-table, which `bin/rails g kiosk:install` lays down too. A challenge issued by one
-process is redeemed by any other. Any other backend works: the contract is
-`put(public_key_pem, nonce, exp)` / `take(public_key_pem, nonce) → Boolean`, and
-`take` **MUST** be one atomic operation (SQL `DELETE … RETURNING`, Redis
-`GETDEL`) so the store, not the application, decides which of two concurrent
-presentations wins.
-
 Events live in `c.event_store`, by default `Kiosk::Server::EventStores::ActiveRecord`:
-the `kiosk.events` table from `bin/rails g kiosk:install`. The event stream runs
+the `kiosk_events` table from `bin/rails g kiosk:install`. The event stream runs
 on the Action Cable adapter that `config/cable.yml` names for the environment. In
 production that adapter must be one every process shares, such as `solid_cable`
 in the host's Gemfile;
@@ -285,9 +337,9 @@ framework decided for your customers' data.
 
 | field | |
 |---|---|
-| `action` | the action's wire name |
-| `user_id` / `agent_id` | the principal, and the assistant credential that acted (nil when the caller is not an agent) |
-| `role` / `actor` | the active role (may be nil), and `"agent"` \| `"human"` \| `"service"` |
+| `action` | the action's published name |
+| `user_id` / `agent_id` | the customer, and the assistant credential that acted (nil when the caller is not an assistant) |
+| `role` / `actor` | the active role (may be nil), and `"agent"` \| `"human"` |
 | `args` | **the arguments exactly as the handler received them** |
 | `status` | `"ok"` or `"error"` |
 | `error_class` / `error_message` | the raised error, untruncated, on the `"error"` branch |
@@ -297,10 +349,10 @@ framework decided for your customers' data.
 ### The arguments arrive unredacted, and the PII is yours
 
 `event.args` is verbatim: the delivery address, the passenger name, the cart,
-the booking reference — whatever your verb takes. **Kiosk does not redact them
+the booking reference — whatever your action takes. **Kiosk does not redact them
 for you, and the moment you write them somewhere you are the data controller
 for whatever they contain** — retention, encryption at rest, access control and
-deletion requests are all yours. That is the deliberate shape of this seam:
+deletion requests are all yours. That is deliberate:
 Kiosk gives you the capability and does not pretend to have made your privacy
 decisions for you.
 
@@ -321,8 +373,8 @@ c.audit_sink = ->(e) { Siem.record(e.to_h.merge(args: e.args.except(:card_token)
 
 Actions only. A **query** is not emitted (it changes nothing, and every read
 would drown the trail). **`pay`** is not emitted — it already writes the far
-richer AP2 mandate trail (`intent_mandates`, `cart_mandates`,
-`payment_mandates`, `settlements`). A **refusal that never reached an action**
+richer AP2 mandate trail (`checkout_mandates`, `payment_mandates`,
+`settlements`). A **refusal that never reached an action**
 is not emitted: a 401 with no identity, a 404 for an unregistered name, a 405,
 a 400 from argument validation, a 402 from the toll. Nothing was invoked, so
 there is nothing to report — this is an action trail, not a request log. Put a
@@ -347,68 +399,69 @@ a boot failure rather than an audit trail that silently was never there.
 
 Bundling the gem draws no route at all, and an origin with no mount answers
 nothing. `bin/rails g kiosk:install` writes the `kiosk` block into
-`config/routes.rb`; you name your verbs in it:
+`config/routes.rb`; you name your operations in it:
 
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
   kiosk do
     queries :catalog
-    actions :place_order
+    actions :create_order
   end
 end
 ```
 
 `kiosk` mounts the engine at `Kiosk.configuration.mount_path`, then draws
 `GET <mount_path>/<name>` for each query and `POST <mount_path>/<name>` for each
-action. Each route reaches the controller action that declares the verb, and
+action. Each route reaches the controller action that declares the operation, and
 `bin/rails routes` prints that action. A block-less `kiosk` only mounts.
 
 **The mount draws the PROTOCOL PLANE** — the paths whose shape is the spec's and
 not yours. Under the mount: the reserved `schema`, `openapi.json` and `pay`,
 `payment_setup` and the `payment_setup/return` page a payment provider sends the
 human back to (both answer `501 module_not_served` without a `payment_provider`), the
-kiosk-pop auth plane (`auth/challenge`, `auth/register`, `auth/login`,
-`auth/revoke`), JWKS (`.well-known/jwks.json`), KYC (`agents/kyc`, and
+OAuth registration and token endpoints (`oauth/register`, `oauth/token`), the key
+rotation (`auth/rotate`), JWKS (`.well-known/jwks.json`), KYC (`agents/kyc`, and
 `request_kyc` and `kyc/callback`, which answer `501 module_not_served` without a
-`kyc_provider`) and the whole account-binding ceremony (the RFC 8628 claim wire,
+`kyc_provider`) and the whole account-binding ceremony (the RFC 8628 claim paths,
 `auth/link`/`claim`/`unlink`, the verify and «Link an assistant» pages). The
 engine also installs the ROOT-relative discovery documents — `/agents.txt`,
 `/agents.json`, `/auth.md`,
-`/.well-known/{agent-configuration,kiosk.json,api-catalog}` — into the host app
+`/.well-known/{kiosk.json,api-catalog,oauth-authorization-server,oauth-protected-resource,ard.json,ai-catalog.json}` and
+`/.well-known/agent-skills/index.json` — into the host app
 via `routes.append`, because the agents.txt standard and RFC 8615 place them at
 the origin root, outside any mount prefix. That install happens ONLY when the
 engine is mounted: merely bundling the gem adds no routes.
 
-**You name your OWN VERBS, and the METHOD FOLLOWS THE KIND** — GET for a
-`kind :query`, POST for a `kind :action`. That is what the protocol says a verb
-IS, so the routes state it instead of hiding it, and `bin/rails routes` prints
-your actual wire.
+**You name your OWN OPERATIONS, and the METHOD FOLLOWS THE KIND** — GET for a
+`kind :query`, POST for a `kind :action`. That is what the protocol says an
+operation IS, so the routes state it instead of hiding it, and `bin/rails routes` prints
+your actual protocol.
 
 **The mount comes FIRST.** Rails dispatches the first matching route, so
-everything the engine draws wins over every verb route and no verb of yours can
-shadow `schema`, `pay` or the auth plane. (You could not declare such a verb
-anyway — `Kiosk::Handler` refuses a reserved name at boot.)
+everything the engine draws wins over every route of an operation, and no
+operation of yours can shadow `schema`, `pay` or the auth plane. (You could not
+declare such an operation anyway — `Kiosk::Handler` refuses a reserved name at boot.)
 
-A path under the mount that names no route — including a verb called with the
+A path under the mount that names no route — including an operation called with the
 other method — matches nothing, so it is the ordinary 404 Rails answers at any
 unrouted path: no `code`, no `hint`. The mount-path middleware still stamps the
-version headers on it. If you want the wire's own `404 verb_not_found` there,
+version headers on it. If you want the protocol's own `404 verb_not_found` there,
 draw a catch-all action of your own at the end of your routes; the engine does not
 draw one, because an assistant reads `GET <mount>/schema` before it dials.
-Declared-but-unrouted is the bug class this trade opens: every verb you declare
-needs its name in the block.
+Declared-but-unrouted is the bug class this trade opens: every operation you
+declare needs its name in the block.
 
 **The protocol plane comes from the mount and from nowhere else.** Copying those
 paths into your routes by hand is not a supported second way to draw them:
 the mount above the copy already answers, so the line is dead, and a protocol
 this gem keeps in step with the spec becomes a table you now own. Write your own
-verbs; mount the rest.
+operations; mount the rest.
 
 
 ## Declaring queries and actions
 
-An assistant reaches a provider at ONE ENDPOINT PER VERB: a query is
+An assistant reaches an operator at ONE PATH PER OPERATION: a query is
 `GET <mount>/<query-name>` with its arguments in the query string, an action is
 `POST <mount>/<action-name>` with its arguments in a JSON body. The operator
 decides what those names are and what they mean. `Kiosk::Handler` is the module
@@ -418,7 +471,7 @@ that lets a controller answer them, and you name each one in the `kiosk` block
 Kiosk ships a **mixin, not a base class**. Which superclass a handler controller
 has is your decision; the `include` is the whole contract.
 
-Which verb reaches a handler is a property of the **declaration**, not of the
+Which HTTP method reaches a handler is a property of the **declaration**, not of the
 class: `kind :query` puts it on `GET`, `kind :action` on `POST`, and one
 controller may declare both — a resource you think of as one thing is one
 controller. Split when your domain splits.
@@ -470,29 +523,29 @@ end
 
 Put handler controllers in `app/controllers/kiosk/`. The engine loads that
 directory at boot and after every development reload, and each class that
-includes `Kiosk::Handler` registers its verbs, so an edited, added or removed
-verb lands without restarting the server.
+includes `Kiosk::Handler` registers its operations, so an edited, added or
+removed operation lands without restarting the server.
 
 
 ### What the macros do
 
 Each macro records a declaration; the **next `def`** claims all pending ones and
-becomes a wire verb. A method with no declarations above it is not a verb, so
-helper methods stay invisible to the wire.
+becomes an operation. A method with no declarations above it is not an operation, so
+helper methods stay invisible to the protocol.
 
 | macro | what it declares |
 | --- | --- |
-| `kind` | **Required.** `:query` (reached by `GET <mount>/<name>`) or `:action` (`POST <mount>/<name>`). A property of the declaration, so one controller may carry both. There is no default: either one would silently pick an HTTP method for you. `:action` is the DECLARATION name and nothing else: the wire command an action travels under is **`:run`**, so a `kind :action` verb reaches a reputation policy as `verb: :run` (`Kiosk::Handler` serves an action as `:run`; the reserved pay endpoint arrives as `:pay`). Branch on `:run` there, not on `:action` — see `kiosk-reputation`'s README. |
-| `reach` | Optional, and the default is the strong one. Whose rows this verb may touch (spec §7.2): `:principal` (default — only the caller's own, or rows that belong to no principal), `:published`, `:consented` or `:role`. Declare nothing and the verb is held to per-principal scoping absolutely; a departure costs one line and is published on the catalog, so an assistant can tell an open board from a scoping bug. |
-| `description` | Semantics **only**: what the verb does, how, and what it returns *in meaning*. Never a field list, a type, a required marker or a param name — those live in the schemas. |
-| `input_schema` | **Required.** JSON Schema for the params. The input contract: every name, type, enum and range — and the wire coerces and validates every call against it. A verb that takes nothing still declares the empty closed object. |
-| `output_schema` | **Required.** JSON Schema for what comes back, so an assistant knows the result shape without a call-and-observe probe — the only machine-readable statement of the answer, now that there is no response envelope. |
+| `kind` | **Required.** `:query` (reached by `GET <mount>/<name>`) or `:action` (`POST <mount>/<name>`). A property of the declaration, so one controller may carry both. There is no default: either one would silently pick an HTTP method for you. `:action` is the DECLARATION name and nothing else: the protocol command an action travels under is **`:run`**, so a `kind :action` operation reaches a reputation policy as `verb: :run` (`Kiosk::Handler` serves an action as `:run`; the reserved `pay` path arrives as `:pay`). Branch on `:run` there, not on `:action` — see `kiosk-reputation`'s README. |
+| `reach` | Optional, and the default is the strong one. Whose rows this operation may touch (spec §7.2): `:principal` (default — only the caller's own, or rows that belong to no customer), `:published`, `:consented` or `:role`. Declare nothing and the operation is held to per-customer scoping absolutely; a departure costs one line and is published on the catalog, so an assistant can tell an open board from a scoping bug. |
+| `description` | Semantics **only**: what the operation does, how, and what it returns *in meaning*. Never a field list, a type, a required marker or a param name — those live in the schemas. |
+| `input_schema` | **Required.** JSON Schema for the params. The input contract: every name, type, enum and range — and the protocol coerces and validates every call against it. An operation that takes nothing still declares the empty closed object. |
+| `output_schema` | **Required.** JSON Schema for what comes back, so an assistant knows the result shape before it calls. The response has no envelope, so this is the only machine-readable statement of the answer. |
 | `example_params` | A params object an assistant can copy verbatim. |
 | `example_row` | A worked example of the result. |
-| `wire_name` | Optional. The name agents call the verb by, when it cannot be the method name. |
+| `wire_name` | Optional. The published name that assistants call the operation by, when it cannot be the method name. |
 
 The **Required** rows are enforced at declaration time, not at request time: a
-verb that omits any of them raises an `ArgumentError` as its class body is read,
+operation that omits any of them raises an `ArgumentError` as its class body is read,
 so the app fails to boot instead of publishing an incomplete contract.
 
 All of them surface in `GET <mount>/schema`, which is how an assistant discovers
@@ -519,15 +572,16 @@ with no restart and no deploy. The catalog's `?v=` version moves with it, and
 the discovery document republishes the new link within its own minute.
 `description`, `kind`, `reach` and `wire_name` are not resolvable — the first is
 prose semantics, two are routing facts fixed when the route is drawn, and
-`reach` is a security claim about the verb: one computed from your rows could
+`reach` is a security claim about the operation: one computed from your rows could
 change under a caller between the catalog it read and the call it made.
 
 
 ### Two things to know
 
-**Draw verb routes with `kiosk` only.** A route you draw at a handler action
-yourself answers 404: the `kiosk` block names the verb that the action answers.
-`Kiosk::Handler` runs authentication, the argument check, the proof-of-work gate
+**Draw the routes of operations with `kiosk` only.** A route you draw at a
+handler action yourself answers 404: the `kiosk` block names the operation that
+the action answers.
+`Kiosk::Handler` runs authentication, the argument check, the proof-of-work toll
 and the transaction around the action, before your own `before_action` filters.
 
 ### What you get inside a handler
@@ -537,7 +591,7 @@ applies, `params` is `ActionController::Parameters`, and the answer is whatever
 you `render` — or the action's JSON template (a Jbuilder view, say), which is
 the one rendered whatever `Accept` the caller sent. On top of that:
 
-- `kiosk_identity` — the `Kiosk::Identity` the wire resolved (`user_id`,
+- `kiosk_identity` — the `Kiosk::Identity` the protocol resolved (`user_id`,
   `agent_id`, `role`, `actor`). The four transaction-local GUCs are already applied to
   the connection, so SQL-side and RLS scoping work whether or not you read it.
 - `render_kiosk_page(rows, next_cursor:, total:)` — answer one page of a large
@@ -546,7 +600,7 @@ the one rendered whatever `Accept` the caller sent. On top of that:
   matching-row count as `X-Total-Count`. `Kiosk::Server::Cursor` has an offset
   helper; pass `total:` only when you know it.
 - `include Kiosk::Owned` — gives a model with a `user_id` column the scope
-  `own`, the current principal's rows. `Kiosk.current_user_id` is the same id,
+  `own`, the signed-in customer's rows. `Kiosk.current_user_id` is the same id,
   for a column with another name.
 - `Kiosk.reader_zone(default = nil)` — the zone the caller declared in
   `Kiosk-Timezone`, else `default`.
@@ -558,28 +612,28 @@ the one rendered whatever `Accept` the caller sent. On top of that:
 - `include Kiosk::SkillLink` — in a page controller: every answer carries
   `Link: <skill_url>; rel="kiosk"`, the discovery signal for a client that
   does not read HTML.
-- `Kiosk::Settlement` and `Kiosk::CartMandate` — read models over the receipts
-  `pay` records. `Kiosk::Settlement.own` is the caller's own;
-  `Kiosk::Settlement.joins(:cart_mandate).merge(Kiosk::CartMandate.referencing(order_id: id))`
-  is the settlement whose cart names your row by the key your line items carry.
-- The handler runs inside the wire's GUC-scoped transaction, so raising rolls
-  back — and so does rendering a non-2xx, which the seam converts into a raise.
-
-Errors are Rails' idiom, end to end. The error-**code** vocabulary is the wire
-contract — a closed table, not a class hierarchy. Mind which side of the seam
+- `Kiosk::Settlement` and `Kiosk::CheckoutMandate` — read models over the
+  records `pay` writes. `Kiosk::Settlement.own` is the caller's own;
+  `Kiosk::Settlement.joins(:checkout_mandate).merge(Kiosk::CheckoutMandate.referencing(order_id: id))`
+  is the settlement whose checkout names your row by the key your line items carry.
+- The handler runs inside the protocol's GUC-scoped transaction, so raising rolls
+  back — and so does rendering a non-2xx, which `Kiosk::Handler` converts into a raise.
+
+Errors are Rails' idiom, end to end. The error-**code** vocabulary is the protocol
+contract — a closed table, not a class hierarchy. Mind which side of `Kiosk::Handler`
 you are on: a handler names a code the Rails way, under `error.code` in the body
-it renders, and the wire re-renders that as an RFC 9457
+it renders, and the protocol re-renders that as an RFC 9457
 `application/problem+json` document whose `code` is a FLAT top-level member —
 `error.code` is the handler-side spelling, `code` is what travels and what an
 assistant branches on. Three Rails-native moves cover all of it:
 
-- `render json: {...}, status: :bad_request` — the status becomes its wire
+- `render json: {...}, status: :bad_request` — the status becomes its protocol
   code (400 `bad_request`, 401 `unauthenticated`, 403 `forbidden`,
   404 `not_found`, 409 `conflict`, 422 `bad_request`, 429 `quota_exceeded`).
 - Raise what you would raise anyway. Any exception Rails knows a status for —
   `params.require`, `ActiveRecord::RecordNotFound`, anything your app
   registered in `config.action_dispatch.rescue_responses` (the same registry
-  policy libraries use) — is mapped to that status' wire code by one
+  policy libraries use) — is mapped to that status' error code by one
   `rescue_from` the include installs. Your own `rescue_from` declarations win
   over it. Anything unregistered stays a 500 `action_failed`.
   **The CODE travels; the exception's own SENTENCE does not.** That branch is
@@ -601,23 +655,23 @@ assistant branches on. Three Rails-native moves cover all of it:
   raisable too.)
 
 
-### The initializer holds configuration, not verbs
+### The initializer holds configuration, not operations
 
-There is no second way to declare a verb — no block you register from an
+There is no second way to declare an operation — no block you register from an
 initializer. A block there cannot be reloaded, cannot be reached by your
 filters, `rescue_from` or strong parameters, and would teach — in the very file
 an adopter copies — that Rails does not apply to the surface you expose to
 assistants. Write a controller in `app/controllers/kiosk/`, and the initializer
 keeps what an initializer is for: the identity providers, the payment provider,
-the PoW gates.
+the toll.
 
 
-## Well-known endpoint (no booted Rails app required)
+## The discovery document (no booted Rails app required)
 
 ```ruby
 require "kiosk/server"
 
-# The issuer is the AP2 mandate `iss` anchor; the builder refuses to answer
+# The issuer is the origin a token or a checkout names; the builder refuses to answer
 # without it, booted app or not.
 Kiosk.configure { |c| c.issuer = "https://api.acme.example" }