kiosk-server 0.6.1 → 0.6.28

data/lib/kiosk/server/pow_gate.rb

@@ -6,10 +6,10 @@ require 'json'
 module Kiosk
   module Server
     # The proof-of-work toll, in front of every verb that reaches the executor.
-    # It is paid once per access token: after one paid toll, every call made
-    # with that token proceeds until the token expires. With no
-    # `reputation_policy` it returns `:proceed` and touches nothing;
-    # `kiosk-reputation` is required only when a policy is set.
+    # The policy decides on each call; a valid proof sets the account's count of
+    # tolled calls back to zero. With no `reputation_policy` it returns
+    # `:proceed` and touches nothing; `kiosk-reputation` is required only when a
+    # policy is set.
     module PowGate
       module_function
 
@@ -21,46 +21,25 @@ module Kiosk
         )
       end
 
-      # `command` is the policy verb ({Executor::VERBS}); `verb` is the wire name
+      # `command` is the policy verb ({Executor::VERBS}); `verb` is the published name
       # the fingerprint binds.
-      def gate(identity:, command:, body:, pow:, method: 'POST', verb: nil) # rubocop:disable Metrics/ParameterLists -- the wire controller and the specs pass these six by name
+      def gate(identity:, command:, body:, pow:, method: 'POST', verb: nil) # rubocop:disable Metrics/ParameterLists -- WireController and the specs pass these six by name
         config = Kiosk.configuration
         policy = config.reputation_policy
-        return :proceed if policy.nil? || session_paid?(config, identity)
+        return :proceed if policy.nil?
 
-        secret = pow_secret!(config)
-        spec   = toll_for(policy, identity, command.to_sym)
+        secret  = pow_secret!(config)
+        factors = ReputationFactors.for(identity:, policy:)
+        spec    = policy.challenge_for(identity: identity, verb: command.to_sym, factors: factors)
         return :proceed if spec.nil?
 
         fp = request_fingerprint(method: method, verb: verb || command, body: body)
         PowToll.new(spec: spec, fingerprint: fp, secret: secret, config: config)
-               .collect!(pow).tap { paid(config, identity) }
-      end
-
-      def session_paid?(config, identity)
-        session = session_id(identity)
-        !session.nil? && config.pow_spent_store.spent?(session)
-      end
-
-      # Records the token's session as paid.
-      def paid(config, identity)
-        session = session_id(identity)
-        config.pow_spent_store.mark_spent(session, identity.claims[:exp]) if session
-      end
-
-      # The access token a toll pays for, by its `jti`, or nil for a caller without one.
-      def session_id(identity)
-        claims = identity&.claims || {}
-        "session:#{claims[:jti]}" if claims[:jti] && claims[:exp]
-      end
-
-      # The policy's toll for this caller and verb, or nil for none.
-      def toll_for(policy, identity, verb)
-        policy.challenge_for(identity: identity, verb: verb, factors: ReputationFactors.for(identity:, policy:))
+               .collect!(pow).tap { TolledCalls.reset!(identity.user_id) if factors.calls_since_proof }
       end
 
       def pow_secret!(config)
-        unless defined?(::Kiosk::Reputation)
+        unless defined?(::Kiosk::Reputation::Challenge)
           raise Errors::ConfigurationError,
                 'Kiosk::Server: reputation_policy is set but kiosk-reputation is not loaded. ' \
                 "Add `require 'kiosk/reputation'` (and `gem 'kiosk-reputation'`) to your app."

data/lib/kiosk/server/pow_spent_stores.rb

@@ -89,7 +89,7 @@ module Kiosk
         end
 
         def connection = ::ActiveRecord::Base.lease_connection
-        def table = %("#{Kiosk.configuration.schema}".pow_spent)
+        def table = %("#{Kiosk.configuration.schema}".kiosk_pow_spent)
       end
     end
   end

data/lib/kiosk/server/receipts.rb

@@ -6,6 +6,8 @@ module Kiosk
     # operator signs as it signs a checkout, each naming its mandate by reference.
     module Receipts
       SUCCESS = 'Success'
+      # AP2 requires a network id; this text stands in when the PSP reports none.
+      NO_NETWORK_ID = 'not reported by the payment provider'
 
       module_function
 
@@ -13,16 +15,15 @@ module Kiosk
       def issue(checkout:, payment:, settlement_id:, psp_reference:, network_confirmation_id:)
         { checkout_receipt: sign(checkout, order_id: order_id(checkout)),
           payment_receipt: sign(payment, payment_id: settlement_id, psp_confirmation_id: psp_reference,
-                                         network_confirmation_id: network_confirmation_id) }
+                                         network_confirmation_id: network_confirmation_id || NO_NETWORK_ID) }
       end
 
       # The id in the checkout's first line item, which names the item paid for (§11.7).
       def order_id(checkout) = checkout.line_items.first.values.first.to_s
 
-      # A network id the PSP did not report is left out.
       def sign(mandate, **claims)
         Checkout.signed({ status: SUCCESS, iss: Kiosk.current_issuer, iat: Time.now.to_i,
-                          reference: mandate.reference, **claims }.compact)
+                          reference: mandate.reference, **claims })
       end
     end
   end

data/lib/kiosk/server/reputation_factors.rb

@@ -3,36 +3,43 @@
 module Kiosk
   module Server
     # The reputation inputs the engine knows itself: what the customer paid
-    # here and kept paid, and the visits the operator recorded, within a policy's window.
+    # here and kept paid, and the visits the operator recorded, within a policy's
+    # window; and the account's tolled calls since its last proof.
     module ReputationFactors
       module_function
 
       # Empty factors unless the policy names a window (`#within`, in seconds).
+      # Reading the factors counts an assistant's call as one more tolled call of its account.
       def for(identity:, policy:)
         return ::Kiosk::Reputation::Factors.empty unless policy.respond_to?(:within) && identity&.user_id
 
         count, cents = recent_spend(identity.user_id, Time.current - policy.within.to_i)
-        ::Kiosk::Reputation::Factors.empty.with(settled_purchases_count: count, settled_purchases_cents: cents)
+        ::Kiosk::Reputation::Factors.new(settled_purchases_count: count, settled_purchases_cents: cents,
+                                         calls_since_proof: identity.agent_id && TolledCalls.count!(identity.user_id))
       end
 
       # Settlements and visits of this customer since `since`: their count and their cents.
       # A settlement counts less what was refunded of it; one refunded in full does not count.
+      # The settlements and visits of each assistant account merged into this account count too.
       def recent_spend(user_id, since)
         sql = format(RECENT_SPEND_SQL, schema: Kiosk.configuration.schema)
         row = ::ActiveRecord::Base.lease_connection.exec_query(sql, 'Kiosk recent spend', [user_id, since]).to_a.first
         [row.fetch('count').to_i, row.fetch('cents').to_i]
       end
 
+      MERGED_SQL = 'SELECT user_id FROM "%<schema>s".kiosk_assistant_accounts WHERE merged_into = $1'
       RECENT_SPEND_SQL = <<~SQL.squish
         SELECT count(*) AS count, COALESCE(SUM(cents), 0) AS cents FROM (
           SELECT s.settled_amount_cents - COALESCE(SUM(r.refunded_amount_cents), 0) AS cents
-            FROM "%<schema>s".settlements s LEFT JOIN "%<schema>s".refunds r ON r.settlement_id = s.id
-            WHERE s.user_id = $1 AND s.settled_at >= $2 GROUP BY s.id
+            FROM "%<schema>s".kiosk_settlements s LEFT JOIN "%<schema>s".kiosk_refunds r ON r.settlement_id = s.id
+            WHERE (s.user_id = $1 OR s.user_id IN (#{MERGED_SQL})) AND s.settled_at >= $2 GROUP BY s.id
             HAVING s.settled_amount_cents > COALESCE(SUM(r.refunded_amount_cents), 0)
           UNION ALL
-          SELECT value_cents FROM "%<schema>s".visits WHERE user_id = $1 AND visited_at >= $2
+          SELECT value_cents FROM "%<schema>s".kiosk_visits
+            WHERE (user_id = $1 OR user_id IN (#{MERGED_SQL})) AND visited_at >= $2
         ) spend
       SQL
+      private_constant :MERGED_SQL
     end
   end
 end

data/lib/kiosk/server/request_validation.rb

@@ -19,6 +19,7 @@ module Kiosk
         'POST <endpoint>/auth/claim' => 'binding.schema.json#/$defs/claimRequest',
         'POST <endpoint>/auth/unlink' => 'binding.schema.json#/$defs/unlinkRequest',
         'POST <endpoint>/agents/kyc' => 'kyc.schema.json#/$defs/request',
+        'POST <endpoint>/kyc/callback' => 'kyc.schema.json#/$defs/callback',
         'POST <endpoint>/pay' => 'mandates.schema.json#/$defs/payRequest'
       }.freeze
 
@@ -34,7 +35,7 @@ module Kiosk
         end
       end
 
-      # A missing member keeps the wire's own `missing field:` sentence.
+      # A missing member keeps the protocol's own `missing field:` sentence.
       def validate_body!(body, exchange:)
         return unless Kiosk.configuration.validate_requests
 

data/lib/kiosk/server/result.rb

@@ -3,7 +3,7 @@
 module Kiosk
   module Server
     # The executor's internal carrier for a successful call; only {#to_payload}
-    # reaches the wire, as the body.
+    # reaches the protocol, as the body.
     class Result < Data.define(:kind, :payload, :next_cursor, :total)
       KINDS = %i[rows value].freeze
 

data/lib/kiosk/server/revocation_stores.rb

@@ -58,7 +58,7 @@ module Kiosk
         private
 
         def connection = ::ActiveRecord::Base.lease_connection
-        def table(name) = %("#{Kiosk.configuration.schema}".#{name})
+        def table(name) = %("#{Kiosk.configuration.schema}".kiosk_#{name})
       end
     end
   end

data/lib/kiosk/server/routing.rb

@@ -38,7 +38,7 @@ module Kiosk
       end
 
       # The endpoint of one verb route. The controller action that declares the
-      # verb answers the wire request; the name is looked up per request, so a
+      # verb answers the protocol request; the name is looked up per request, so a
       # development reload is served. A name that no action answers goes to
       # {VerbController}, which refuses it.
       class VerbRoute

data/lib/kiosk/server/schemas/auth.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kiosk.tech/spec/schemas/auth.schema.json",
-  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/auth.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/auth.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE HTTP bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
   "title": "Kiosk client registration and tokens (OAuth)",
-  "description": "The wire objects of Section 5: RFC 7591 open client registration of the AI assistant's public key, RFC 7523 client assertions signed with that key (the private_key_jwt method), and DPoP-bound access tokens from the client_credentials grant (RFC 9449). The roots are open: they state what MUST be present and the shape of each member.",
+  "description": "The protocol objects of Section 5: RFC 7591 open client registration of the AI assistant's public key, RFC 7523 client assertions signed with that key (the private_key_jwt method), and DPoP-bound access tokens from the client_credentials grant (RFC 9449). The roots are open: they state what MUST be present and the shape of each member.",
   "$defs": {
     "publicJwk": {
       "type": "object",

data/lib/kiosk/server/schemas/binding.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kiosk.tech/spec/schemas/binding.schema.json",
-  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/binding.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/binding.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE HTTP bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
   "title": "Kiosk account binding -- claim and link",
-  "description": "The wire objects of Section 6, the one-time ceremonies that bind a registered AI assistant to an existing operator account: claim, an RFC 8628 device grant, and link. Both need the human's approval and a client assertion by the registered key. The two /oauth/* requests are form-encoded and have no schema here; their answers are in auth.schema.json.",
+  "description": "The protocol objects of Section 6, the one-time ceremonies that bind a registered AI assistant to an existing operator account: claim, an RFC 8628 device grant, and link. Both need the human's approval and a client assertion by the registered key. The two /oauth/* requests are form-encoded and have no schema here; their answers are in auth.schema.json.",
   "$defs": {
     "deviceAuthorization": {
       "type": "object",
@@ -51,7 +51,7 @@
     },
     "oauthError": {
       "$ref": "https://kiosk.tech/spec/schemas/auth.schema.json#/$defs/oauthError",
-      "description": "Section 6.1: the error answer of both /oauth/* endpoints, the one error shape on this wire that is not an RFC 9457 problem document."
+      "description": "Section 6.1: the error answer of both /oauth/* endpoints, the one error shape in this protocol that is not an RFC 9457 problem document."
     },
     "linkCode": {
       "type": "object",

data/lib/kiosk/server/schemas/kyc.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kiosk.tech/spec/schemas/kyc.schema.json",
-  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/kyc.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/kyc.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE HTTP bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
   "title": "Kiosk KYC attestation",
-  "description": "The decoded JWS payload of a KYC attestation, the POST /kiosk/agents/kyc request body, the request_kyc answer, and the data of the kyc_verification event that delivers the attestation.",
+  "description": "The decoded JWS payload of a KYC attestation, the POST /kiosk/agents/kyc request body, the request_kyc answer, the body that the KYC provider posts to the callback and its answer, and the data of the kyc_verification event that delivers the attestation.",
   "$defs": {
     "attestation": {
       "type": "object",
@@ -13,7 +13,7 @@
         "sub": { "type": "string", "description": "MUST equal the authenticated user_id." },
         "level": { "const": "verified", "description": "Binary; anything other than \"verified\" is rejected." },
         "iss": { "type": "string", "description": "MUST equal the provider-configured KYC issuer." },
-        "aud": { "type": "string", "description": "OPERATOR-BINDING. The operator the attestation was minted for. MUST equal the operator's configured kyc_audience (its origin, or a stable handle it declares); the operator rejects any other aud. This stops a claim minted for operator A being replayed to operator B." },
+        "aud": { "type": "string", "description": "OPERATOR-BINDING. The operator the attestation was minted for. MUST equal the audience the operator's KYC provider mints for it (its origin, or a stable handle it registered); the operator rejects any other aud. This stops a claim minted for operator A being replayed to operator B." },
         "iat": { "type": "integer", "description": "Issued-at timestamp. Not enforced by the verifier." },
         "exp": { "type": "integer", "description": "One year after iat. An expired attestation is rejected." },
         "attributes": { "$ref": "#/$defs/attributes" }
@@ -42,6 +42,25 @@
         "status": { "const": "pending" }
       }
     },
+    "callback": {
+      "type": "object",
+      "description": "The body that the KYC provider posts to POST <endpoint>/kyc/callback when the human approves (Section 12.4.1). The operator answers 403 unless nonce equals the one that it kept.",
+      "required": ["request_id", "kyc_jws"],
+      "properties": {
+        "request_id": { "type": "string", "description": "The provider's id for the verification that request_kyc opened." },
+        "nonce": { "type": "string", "description": "The one-time nonce that the provider gave the operator when it opened the verification." },
+        "kyc_jws": { "type": "string", "description": "The attestation as a compact EdDSA JWS." }
+      }
+    },
+    "callbackAnswer": {
+      "type": "object",
+      "description": "The operator's 200 answer to a callback that it accepted.",
+      "additionalProperties": false,
+      "required": ["ok"],
+      "properties": {
+        "ok": { "const": true }
+      }
+    },
     "verificationEvent": {
       "type": "object",
       "description": "The data of a kyc_verification event: the human approved, and the event carries the provider-signed attestation to submit to POST /kiosk/agents/kyc.",

data/lib/kiosk/server/schemas/mandates.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kiosk.tech/spec/schemas/mandates.schema.json",
-  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/mandates.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/mandates.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE HTTP bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
   "title": "Kiosk payment: the checkout and the AP2 v0.2 mandates",
-  "description": "The checkout an operator signs, the two closed AP2 v0.2 mandates an AI assistant signs to pay it, the POST <endpoint>/pay request body, the settlement it answers and the two receipts in it. On the wire the checkout is a compact EdDSA JWT, and each mandate is a compact SD-JWT whose one disclosure is the mandate; these schemas describe the decoded objects.",
+  "description": "The checkout an operator signs, the two closed AP2 v0.2 mandates an AI assistant signs to pay it, the POST <endpoint>/pay request body, the settlement it answers and the two receipts in it. Over HTTP the checkout is a compact EdDSA JWT, and each mandate is a compact SD-JWT whose one disclosure is the mandate; these schemas describe the decoded objects.",
   "$defs": {
     "currency": {
       "type": "string",
@@ -143,8 +143,8 @@
     },
     "paymentReceipt": {
       "type": "object",
-      "description": "The claims of the payment receipt a successful pay answers (AP2 v0.2 payment_receipt.json, status Success). `network_confirmation_id` is present only when the payment provider reports it; AP2 requires it, so a receipt without it does not satisfy AP2's schema (protocol.md 11.3).",
-      "required": ["status", "iss", "iat", "reference", "payment_id", "psp_confirmation_id"],
+      "description": "The claims of the payment receipt a successful pay answers (AP2 v0.2 payment_receipt.json, status Success).",
+      "required": ["status", "iss", "iat", "reference", "payment_id", "psp_confirmation_id", "network_confirmation_id"],
       "properties": {
         "status": { "const": "Success" },
         "iss": { "type": "string", "description": "The operator's issuer." },
@@ -152,7 +152,7 @@
         "reference": { "type": "string", "description": "The reference of the payment mandate: the base64url SHA-256 of its compact SD-JWT." },
         "payment_id": { "type": "string", "description": "The settlement_id." },
         "psp_confirmation_id": { "type": "string", "description": "The psp_reference." },
-        "network_confirmation_id": { "type": "string", "description": "The card network's id of the transaction." }
+        "network_confirmation_id": { "type": "string", "minLength": 1, "description": "The card network's id of the transaction, or `not reported by the payment provider` when the payment provider reports none (protocol.md 11.3)." }
       }
     }
   }

data/lib/kiosk/server/schemas/pow.schema.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://kiosk.tech/spec/schemas/pow.schema.json",
-  "title": "Kiosk proof-of-work",
   "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/pow.schema.json. This file is self-contained (no cross-file $ref) and must be kept in sync with the upstream normative copy.",
+  "title": "Kiosk proof-of-work",
   "description": "The PoW challenge object (issued in a pow_required 402) and the proof(s) an agent returns in the Kiosk-PoW request header (raw JSON) on retry.",
   "$ref": "#/$defs/powHeader",
   "$defs": {
@@ -71,7 +71,7 @@
           }
         },
         "header_nonce": {
-          "$comment": "The bound is stated as an INCLUSIVE `maximum` of 2**32-1, matching how `indices` states its own: 4294967295 is exactly representable as an IEEE-754 double, so it survives any JSON parser, and an inclusive bound never refuses the largest legal value. Without a bound the field is unbounded on the wire while both specs call it a u32 -- and the reference verifier folds it in with `pack(\"V\")`, which truncates mod 2**32 instead of raising, so 0, 2**32 and -(2**32) seed identically and one proof has infinitely many spellings. The verifier rejects out-of-range values for the same reason; schema and verifier state one bound, not two.",
+          "$comment": "The bound is stated as an INCLUSIVE `maximum` of 2**32-1, matching how `indices` states its own: 4294967295 is exactly representable as an IEEE-754 double, so it survives any JSON parser, and an inclusive bound never refuses the largest legal value. Without a bound the field is unbounded in the JSON while both specs call it a u32 -- and the reference verifier folds it in with `pack(\"V\")`, which truncates mod 2**32 instead of raising, so 0, 2**32 and -(2**32) seed identically and one proof has infinitely many spellings. The verifier rejects out-of-range values for the same reason; schema and verifier state one bound, not two.",
           "type": "integer",
           "minimum": 0,
           "maximum": 4294967295,

data/lib/kiosk/server/session_context.rb

@@ -2,7 +2,7 @@
 
 module Kiosk
   module Server
-    # The identity a wire request runs as. {#open} wraps the request in a
+    # The identity a protocol request runs as. {#open} wraps the request in a
     # transaction and sets the principal's GUCs transaction-locally, for
     # operators who opt into RLS.
     class SessionContext
@@ -19,7 +19,7 @@ module Kiosk
 
       def self.open? = !Thread.current[KEY].nil?
 
-      # The identity the wire resolved. Raises outside a session, where a scope
+      # The identity the protocol resolved. Raises outside a session, where a scope
       # built on it would otherwise match nothing.
       def self.identity
         return current.identity if open?

data/lib/kiosk/server/tolled_calls.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Each account's tolled calls since its last proof, in
+    # `tolled_calls.calls_since_proof`. The count belongs to the account: the
+    # assistants bound to one account share it, and a new access token or a
+    # new key does not set it back.
+    module TolledCalls
+      module_function
+
+      # Adds this call and answers the account's count, this call included.
+      # One statement, so calls made at the same time each get their own number.
+      def count!(user_id)
+        sql = <<~SQL.squish
+          INSERT INTO "#{schema}".kiosk_tolled_calls AS t (user_id, calls_since_proof) VALUES ($1, 1)
+          ON CONFLICT (user_id) DO UPDATE SET calls_since_proof = t.calls_since_proof + 1
+          RETURNING calls_since_proof
+        SQL
+        connection.exec_query(sql, 'Kiosk tolled call', [user_id]).rows.dig(0, 0)
+      end
+
+      # A valid proof sets the count back to zero.
+      def reset!(user_id)
+        connection.exec_query(%(UPDATE "#{schema}".kiosk_tolled_calls SET calls_since_proof = 0 WHERE user_id = $1),
+                              'Kiosk tolled calls reset', [user_id])
+        nil
+      end
+
+      # A binding adds the previous account's count to the new account's, so a
+      # binding never lowers the count of the calls an assistant made.
+      def carry!(from:, to:)
+        sql = <<~SQL.squish
+          INSERT INTO "#{schema}".kiosk_tolled_calls AS t (user_id, calls_since_proof)
+          SELECT $2, calls_since_proof FROM "#{schema}".kiosk_tolled_calls WHERE user_id = $1
+          ON CONFLICT (user_id) DO UPDATE SET calls_since_proof = t.calls_since_proof + excluded.calls_since_proof
+        SQL
+        connection.exec_query(sql, 'Kiosk tolled calls carry', [from, to])
+        nil
+      end
+
+      def connection = ::ActiveRecord::Base.lease_connection
+      def schema = Kiosk.configuration.schema
+    end
+  end
+end

data/lib/kiosk/server/verb_wire.rb

@@ -4,10 +4,10 @@ require 'json'
 
 module Kiosk
   module Server
-    # The gates of a call on the wire, in order: identity (401), the arguments
+    # The gates of a call in the protocol, in order: identity (401), the arguments
     # (400), the caller's timezone (400) and the toll (402). Then the call runs
     # inside a session. {WireController} and every controller that includes
-    # {Kiosk::Handler} serve the wire with them.
+    # {Kiosk::Handler} serve the protocol with them.
     module VerbWire
       include WireRendering
 
@@ -51,7 +51,7 @@ module Kiosk
         raise Errors.malformed_json(hint: BODY_HINT)
       end
 
-      # A {Result}. `command` is the policy verb ({Executor::VERBS}); `name` the wire name;
+      # A {Result}. `command` is the policy verb ({Executor::VERBS}); `name` the published name;
       # `handler` answers in place of the registered one.
       def call_wire(command:, args:, identity:, name:, handler: nil)
         # Refused with the arguments, before the toll.

data/lib/kiosk/server/version.rb

@@ -2,6 +2,6 @@
 
 module Kiosk
   module Server
-    VERSION = '0.6.1'
+    VERSION = '0.6.28'
   end
 end

data/lib/kiosk/server/well_known.rb

@@ -33,6 +33,11 @@ module Kiosk
                           'browse, order, book, apply, pay -- and subscribe to the operator\'s event ' \
                           'stream for anything that you would otherwise wait for.'
 
+      # The one scope value. An AI assistant does not choose its role: the
+      # token request grants the role of its assistant account, whatever scope
+      # it names (RFC 6749 Section 3.3).
+      SCOPES = %w[default].freeze
+
       ARD_API = 'The Kiosk discovery document of this origin: the endpoint, the sign-in and the catalogue. ' \
                 'Read it with the Kiosk skill.'
 
@@ -84,20 +89,18 @@ module Kiosk
         doc = { issuer: Kiosk.current_issuer, registration_endpoint: "#{endpoint}/oauth/register",
                 token_endpoint: "#{endpoint}/oauth/token" }
         doc[:device_authorization_endpoint] = "#{endpoint}/oauth/device_authorization" if config.serve_account_binding
-        # No authorization endpoint, so no response type. An AI assistant
-        # requests no scope, so no scope value.
-        doc.merge(jwks_uri: "#{endpoint}/.well-known/jwks.json", response_types_supported: [], scopes_supported: [],
+        # No authorization endpoint, so no response type.
+        doc.merge(jwks_uri: "#{endpoint}/.well-known/jwks.json", response_types_supported: [], scopes_supported: SCOPES,
                   grant_types_supported: Client.grant_types(config), **Shared.client_authentication,
                   service_documentation: "#{base}/auth.md", dpop_signing_alg_values_supported: AssistantKey.algorithms)
       end
 
       # `/.well-known/oauth-protected-resource` (RFC 9728). RFC 9728 §3.3 binds a
-      # document at this path to the origin, so `resource` is the origin. An
-      # AI assistant requests no scope, so `scopes_supported` is empty.
+      # document at this path to the origin, so `resource` is the origin.
       def self.oauth_protected_resource(base_url:, config: Kiosk.configuration)
         Shared.validate_issuer!(config)
         base = base_url.to_s.chomp('/')
-        { resource: base, authorization_servers: [Kiosk.current_issuer], scopes_supported: [],
+        { resource: base, authorization_servers: [Kiosk.current_issuer], scopes_supported: SCOPES,
           bearer_methods_supported: ['header'],
           dpop_signing_alg_values_supported: AssistantKey.algorithms, dpop_bound_access_tokens_required: true,
           resource_documentation: "#{base}/auth.md" }
@@ -213,7 +216,7 @@ module Kiosk
           return '' unless skill?(config)
 
           sha = config.skill_sha256
-          line = "- Wire skill for AI assistants: #{config.skill_url}"
+          line = "- Skill for AI assistants: #{config.skill_url}"
           line += " (sha256 `#{sha}`)" if sha && !sha.to_s.empty?
           line
         end
@@ -277,7 +280,7 @@ module Kiosk
             # auth.md — #{site}
 
             How AI assistants authenticate against this provider's Kiosk
-            endpoint (`#{endpoint}`). Wire contract: the Kiosk specification
+            endpoint (`#{endpoint}`). Protocol: the Kiosk specification
             (https://kiosk.tech/specification.html). This file follows the
             auth.md section order. Registration and tokens use OAuth 2.0
             standards: RFC 7591, RFC 7523, RFC 9449 and RFC 8628.
@@ -338,7 +341,7 @@ module Kiosk
             `Kiosk-PoW` header line for each proof. A proof is never in the
             request body: the operator ignores a body `pow` field, and a
             changed body makes the proofs incorrect. The same header answers a
-            `402 pow_required` on the wire verbs too. Most of them are GETs,
+            `402 pow_required` on the verbs too. Most of them are GETs,
             which have no body. The ONE endpoint under `#{endpoint}` that has
             no toll is `GET #{endpoint}/schema`: it is public, the operator
             serves it from memory, and a toll needs an identity to charge.
@@ -349,7 +352,7 @@ module Kiosk
             check failed. Get the reference solver from
             `#{PowGate::POW_SOLVER_URL}`. The 403 `hint` names the same file.
             That URL has no version and always serves the CURRENT solver.
-            Before you run it, compare its SHA-256 with the pin that the wire
+            Before you run it, compare its SHA-256 with the pin that the
             skill above publishes.
 
             ## Claim ceremony
@@ -408,7 +411,7 @@ module Kiosk
 
             ## Use the access_token
 
-            Send `Authorization: DPoP <access_token>` to the wire verbs
+            Send `Authorization: DPoP <access_token>` to the verbs
             under `#{endpoint}` (every query, every action, and `pay`) with a
             `DPoP` header: a proof (RFC 9449) that your registered key signs
             for that method and URL, with `ath`, the hash of the token. A

data/lib/kiosk/server/wire_rendering.rb

@@ -4,7 +4,7 @@ require 'cgi'
 
 module Kiosk
   module Server
-    # How a wire answer is written: headers, cache policy, body. Success is the
+    # How a protocol answer is written: headers, cache policy, body. Success is the
     # verb's payload; a refusal is an RFC 9457 problem document.
     module WireRendering
       private

data/lib/kiosk/server.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# kiosk-server: the Rails engine, its wire, auth and discovery controllers, and
+# kiosk-server: the Rails engine, its protocol, auth and discovery controllers, and
 # the install generator. See https://kiosk.tech.
 
 require 'kiosk'
@@ -17,7 +17,11 @@ module Kiosk
   module Server
   end
 
-  # The user id and role of the principal the wire resolved.
+  # Kiosk's tables are `kiosk_*` in the configured schema; Rails names every
+  # model in this namespace with it: Kiosk::Settlement is `public.kiosk_settlements`.
+  def self.table_name_prefix = "#{configuration.schema}.kiosk_"
+
+  # The user id and role of the principal the protocol resolved.
   def self.current_user_id = Server::SessionContext.identity.user_id
   def self.current_role    = Server::SessionContext.identity.role