kiosk-server 0.5.20 → 0.6.1

data/app/controllers/kiosk/server/oauth_token_controller.rb

@@ -4,55 +4,56 @@ require 'action_controller'
 
 module Kiosk
   module Server
-    # POST <endpoint>/oauth/token: the assistant polls the claim ceremony
-    # (RFC 8628 §3.4). Only the device_code grant is served.
+    # POST <endpoint>/oauth/token (RFC 6749 Section 3.2): a registered client
+    # authenticates with a client assertion (RFC 7523) and a DPoP proof of its
+    # registered key (RFC 9449), and gets an access token bound to that key.
+    # The client_credentials grant is always served; the device-code grant
+    # (RFC 8628 Section 3.4) only where the origin serves account binding.
     class OauthTokenController < ::ActionController::API
-      include BindingModuleGate
       include AuthController::Answers
       include AuthController::Proofs
-
-      prepend_before_action :refuse_unserved_binding
-
-      UNSUPPORTED_GRANT = 'only the device_code grant is served here — ' \
-                          'kiosk-pop (POST /auth/login) is the token-refresh path'
+      include OauthAnswers
 
       def create
         case params[:grant_type].to_s
-        when DeviceCodeGrant::GRANT_TYPE then handle_device_code_grant
-        when '' then render_oauth_error(:invalid_request, 'grant_type required', status: 400)
-        else render_oauth_error(:unsupported_grant_type, UNSUPPORTED_GRANT, status: 400)
+        when Client::CLIENT_CREDENTIALS then render_token(authenticated_client)
+        when Client::DEVICE_CODE then device_code_grant
+        when '' then raise OauthError.new(:invalid_request, 'grant_type required')
+        else raise OauthError.new(:unsupported_grant_type, unsupported_grant)
         end
+      rescue OauthError => e
+        render_oauth_error(e)
+      rescue Errors::Base => e
+        render_error(e)
       end
 
       private
 
-      # The auth toll answers with its own problem documents (§10); every other refusal is OAuth's.
-      def handle_device_code_grant
-        result = DeviceCodeGrant.exchange(device_code: params[:device_code].to_s, signed: params[:signed], pow: proofs)
-        Kiosk::Server::Headers.add_to(response.headers)
-        return render json: token_body(result) if result[:ok]
+      # The toll comes before the client authenticates and before the code is read.
+      def device_code_grant
+        device_code = params[:device_code].to_s
+        raise OauthError.new(:unsupported_grant_type, unsupported_grant) unless Kiosk.configuration.serve_account_binding
+        raise OauthError.new(:invalid_request, 'device_code parameter required') if device_code.empty?
 
-        render_grant_failure(result)
-      rescue Errors::Base => e
-        render_error(e)
+        DeviceCodeGrant.pay_toll!(device_code, proofs)
+        render_token(DeviceCodeGrant.exchange(device_code: device_code, client: authenticated_client))
       end
 
-      # RFC 6749 §5.2: invalid_client — the possession proof failed —
-      # is the one error the server SHOULD signal with 401.
-      def render_grant_failure(result)
-        status = result[:error] == 'invalid_client' ? 401 : 400
-        render json: { error: result[:error], error_description: result[:description] }, status: status
-      end
+      def unsupported_grant = "the grant types served here are #{Client.grant_types.join(', ')}"
 
-      def token_body(result)
-        body = { access_token: result[:access_token], token_type: result[:token_type], expires_in: result[:expires_in] }
-        body[:scope] = result[:scope] if result[:scope]
-        body
+      # The client assertion, then the DPoP proof of the registered key.
+      def authenticated_client
+        client = authenticate_client!
+        Dpop.verify_token_request!(request.headers['DPoP'], jkt: client.thumbprint, url: "#{Kiosk.current_issuer}#{request.path}")
+        client
       end
 
-      def render_oauth_error(code, description, status:)
-        Kiosk::Server::Headers.add_to(response.headers)
-        render json: { error: code.to_s, error_description: description }, status: status
+      # RFC 6749 Section 5.1. The scope is the role of the client.
+      def render_token(client)
+        token = AgentIdentityProviders::DefaultAgentIdp.new.issue(agent_id: client.id, role: client.role)
+        body = { access_token: token, token_type: Dpop::SCHEME, expires_in: Kiosk.configuration.access_token_ttl }
+        body[:scope] = client.role if client.role
+        render_oauth(body)
       end
     end
   end

data/app/models/kiosk/checkout_mandate.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kiosk
+  # The checkout mandate the engine records when it settles a `pay`: the line
+  # items of the operator's checkout that the assistant agreed to pay for.
+  # Read-only for the operator.
+  class CheckoutMandate < Server::ApplicationRecord
+    def self.table_name = "#{Kiosk.configuration.schema}.checkout_mandates"
+
+    has_many :settlements, class_name: 'Kiosk::Settlement', dependent: nil, inverse_of: :checkout_mandate
+
+    # Checkout mandates with a line item carrying these attributes, by jsonb
+    # containment: `referencing(order_id: id)` matches `[{"order_id": id, "qty": 2}]`.
+    # The values are quoted by the adapter, never interpolated.
+    scope :referencing, lambda { |**attributes|
+      where(Arel::Nodes::InfixOperation.new(
+              '@>', arel_table[:line_items],
+              Arel::Nodes.build_quoted([attributes.transform_values(&:to_s)].to_json)
+            ))
+    }
+  end
+end

data/app/models/kiosk/settlement.rb

@@ -7,6 +7,6 @@ module Kiosk
 
     def self.table_name = "#{Kiosk.configuration.schema}.settlements"
 
-    belongs_to :cart_mandate, class_name: 'Kiosk::CartMandate', inverse_of: :settlements
+    belongs_to :checkout_mandate, class_name: 'Kiosk::CheckoutMandate', inverse_of: :settlements
   end
 end

data/lib/generators/kiosk/install/install_generator.rb

@@ -106,11 +106,6 @@ module Kiosk
                            'db/migrate/create_kiosk_revocations.rb'
       end
 
-      def create_auth_challenges_migration
-        migration_template 'create_kiosk_auth_challenges.rb.tt',
-                           'db/migrate/create_kiosk_auth_challenges.rb'
-      end
-
       def create_visits_migration
         migration_template 'create_kiosk_visits.rb.tt',
                            'db/migrate/create_kiosk_visits.rb'

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 # Migration 005 — kiosk AP2 mandate trail:
-# intent_mandates, cart_mandates, payment_mandates, settlements.
-# See the Payment (AP2 mandate chain) section of the spec.
+# checkout_mandates, payment_mandates, settlements.
+# See the Payment (AP2 mandates) section of the spec.
 class CreateKioskMandates < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
   def up
     execute <<~'SQL'
@@ -12,10 +12,9 @@ class CreateKioskMandates < ActiveRecord::Migration[ActiveRecord::Migration.curr
 
   def down
     # Reverse-FK order: payment_mandates and settlements both reference
-    # cart_mandates, so both drop before it; cart_mandates before intent_mandates.
+    # checkout_mandates, so both drop before it.
     execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".payment_mandates)
     execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".settlements)
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".cart_mandates)
-    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".intent_mandates)
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".checkout_mandates)
   end
 end

data/lib/kiosk/payable.rb

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

data/lib/kiosk/server/account_binding.rb

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

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

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

data/lib/kiosk/server/agent_rotation.rb

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

data/lib/kiosk/server/assistant_key.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Kiosk
+  module Server
+    # The public key of an AI assistant: the key it registers, signs its client
+    # assertions, DPoP proofs and mandates with, and binds its tokens to. An
+    # Ed25519 key signs EdDSA. A P-256 key signs ES256 where the operator
+    # accepts ES256 (`c.assistant_algorithms`).
+    module AssistantKey
+      # The members of a JWK that only a private key has.
+      PRIVATE_MEMBERS = %w[d].freeze
+
+      module_function
+
+      # The algorithms this operator accepts, EdDSA first. Client assertions,
+      # DPoP proofs, mandates and every metadata list read this list.
+      def algorithms = Kiosk.configuration.assistant_algorithms
+
+      def hint
+        keys = ['an Ed25519 key as an RFC 8037 JWK {"kty":"OKP","crv":"Ed25519","x":"…"}']
+        keys << 'a P-256 key as an RFC 7518 JWK {"kty":"EC","crv":"P-256","x":"…","y":"…"}' if algorithms.include?('ES256')
+        "send one public key: #{keys.join(', or ')}, with no private member"
+      end
+
+      # The key of an RFC 7517 JWK Set that holds exactly one public key.
+      # @raise [Errors::BadRequest] naming what is wrong
+      def from_jwks(jwks)
+        keys = jwks.is_a?(Hash) ? (jwks['keys'] || jwks[:keys]) : nil
+        refuse!('jwks must be a JWK Set with exactly one key') unless keys.is_a?(Array) && keys.size == 1
+
+        from_jwk(keys.first)
+      end
+
+      # @raise [Errors::BadRequest] naming what is wrong
+      def from_jwk(jwk)
+        refuse!('the key is not a JWK object') unless jwk.is_a?(Hash)
+        jwk = jwk.transform_keys(&:to_s)
+        refuse!('the key carries a private member') if jwk.keys.intersect?(PRIVATE_MEMBERS)
+        refuse!("the key is not an #{curves} key") unless key_types.include?(jwk['kty'])
+
+        accepted(Jwk.import(jwk))
+      rescue ArgumentError => e
+        refuse!(e.message)
+      end
+
+      # The key of a row of the agents table.
+      # @raise [Errors::BadRequest] when this operator does not accept the key
+      def from_pem(pem)
+        accepted(OpenSSL::PKey.read(pem.to_s))
+      rescue OpenSSL::PKey::PKeyError
+        refuse!('the key is not a valid public key')
+      end
+
+      # The form the agents table stores.
+      def to_pem(key) = key.public_to_pem.strip
+
+      # RFC 7517: the public members only.
+      def to_jwk(key) = Jwk.public_members(key)
+
+      # RFC 7638.
+      def thumbprint(key) = Jwk.thumbprint(key)
+
+      # The one algorithm `key` signs with.
+      def algorithm(key) = Jwk.algorithm(key)
+
+      # `OKP`, and `EC` where ES256 is accepted.
+      def key_types = algorithms.map { Jwk::ALGORITHMS.key(it) }
+
+      def curves = key_types.map { Jwk::CURVES[it] }.join(' or ')
+
+      def accepted(key)
+        refuse!('the key is a private key') if Jwk.private?(key)
+        refuse!("the key is not an #{curves} key") unless algorithms.include?(algorithm(key))
+        key
+      end
+
+      def refuse!(detail)
+        raise Errors::BadRequest.new(detail, hint: hint)
+      end
+
+      private_class_method :key_types, :curves, :accepted, :refuse!
+    end
+  end
+end

data/lib/kiosk/server/auth_toll.rb

@@ -3,7 +3,7 @@
 module Kiosk
   module Server
     # Optional proof-of-work toll on the auth requests that come before a
-    # token: `POST /auth/register`, the link-code claim `POST /auth/claim`, and
+    # token: `POST /oauth/register`, the link-code claim `POST /auth/claim`, and
     # the first token poll of each device code. It runs before any lookup, so
     # the answer never tells a caller whether a key or a code exists. It bounds
     # the cost per request, not the rate: an edge rate limit is required

data/lib/kiosk/server/binding_module_gate.rb

@@ -7,7 +7,7 @@ module Kiosk
     # `/oauth/*` it is the one problem document served instead of an OAuth error.
     module BindingModuleGate
       DETAIL = 'this operator does not serve the account binding module'
-      HINT   = "register a fresh assistant account at this origin's register_url instead"
+      HINT   = "use this origin with a client of your own: register it at this origin's registration_url"
 
       private