kiosk-server 0.5.20 → 0.6.28

data/app/channels/kiosk_events.rb

@@ -3,7 +3,7 @@
 require 'action_cable'
 
 # Top level, unsuffixed, because Action Cable constantizes the channel named
-# in a subscribe frame: this class name IS the wire's channel name.
+# in a subscribe frame: this class name IS the protocol's channel name.
 #
 #   {"command":"subscribe",
 #    "identifier":"{\"channel\":\"KioskEvents\",\"topic\":\"todo\",\"subject\":\"list_4f1e…\"}"}
@@ -28,15 +28,14 @@ class KioskEvents < ActionCable::Channel::Base
     assign(declaration)
     return reject unless reachable?(declaration)
 
-    open_stream!
-    transmit(subscribed_frame)
+    transmit(open_delivery!)
   end
 
   # Action Cable confirms once the pubsub subscription is live, so replay
   # starts here: an event emitted before that reaches the client this way.
   def transmit_subscription_confirmation
     super
-    replay!
+    @replay.confirmed
   end
 
   private
@@ -59,13 +58,10 @@ class KioskEvents < ActionCable::Channel::Base
     }
   end
 
-  # Everything after `since`, or after the head read before the stream
-  # opened. An event may arrive twice; delivery is at-least-once and the
-  # client ignores an `id` it has seen.
-  def replay!
-    store.since(identity_key, since || @head).each do |event|
-      transmit(event) if for_this_subscription?(event)
-    end
+  # Replay and live delivery both come here, through {Kiosk::Server::EventsReplay}.
+  # An event can arrive twice; the client ignores an `id` it has seen.
+  def deliver(event)
+    transmit(event) if for_this_subscription?(event)
   end
 
   def since = params[:since]
@@ -80,17 +76,33 @@ class KioskEvents < ActionCable::Channel::Base
     (since.nil? || cursor?(since)) && (params[:subject].nil? || params[:subject].is_a?(String))
   end
 
-  def open_stream!
-    # Before the stream opens, so no event falls between head and stream.
+  # Reads head before the stream opens, so no event falls between head and
+  # stream. Returns the `subscribed` frame, built before the replay group
+  # counts this subscription.
+  def open_delivery!
     @head = store.head
+    subscribed_frame.tap do
+      @replay = connection.kiosk_replay_member(since || @head) { |event| deliver(event) }
+      open_stream!
+    end
+  end
 
-    # Without `coder:` the block receives the raw broadcast String.
+  # Without `coder:` the block receives the raw broadcast String.
+  def open_stream!
     stream_from Kiosk::Server::EventsCable.stream_name(identity_key, @topic),
                 coder: ActiveSupport::JSON do |event|
-      transmit(event) if for_this_subscription?(event)
+      @replay.live(event)
+    rescue StandardError => e
+      logger&.error("[kiosk] events delivery failed for topic #{@topic.inspect}: #{e.class}: #{e.message}")
     end
   end
 
+  # On the pubsub's own thread, in the order it hands events over (spec
+  # Section 8.5.5). Action Cable's worker pool would reorder them.
+  def worker_pool_stream_handler(broadcasting, user_handler, coder: nil)
+    stream_handler(broadcasting, user_handler, coder:)
+  end
+
   def cursor?(value) = value.is_a?(Integer) && value.between?(0, MAX_CURSOR)
 
   # Its own topic (the replayed tail holds every topic) and, when named, its
@@ -124,14 +136,15 @@ class KioskEvents < ActionCable::Channel::Base
   end
 
   # Runs every REAUTHORISE_EVERY_SECONDS. A withdrawn reach is final for this
-  # subscription, so the declaration is dropped and the frame sent once.
+  # subscription: the frame is sent once, and the subscription leaves the
+  # connection, so a later subscribe is judged again rather than confirmed as live.
   def reauthorise!
     return if @declaration.nil? || reachable?(@declaration)
 
     @declaration = nil
     # Braces required: bare pairs would be read as `transmit`'s keywords.
     transmit({ 'type' => 'unsubscribed', 'topic' => @topic, 'reason' => 'reach_revoked' })
-    stop_all_streams
+    connection.subscriptions.remove_subscription(self)
   rescue StandardError => e
     logger&.error("[kiosk] events re-authorisation failed: #{e.class}: #{e.message}")
   end

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

@@ -9,7 +9,6 @@ module Kiosk
     class ApplicationController < ::ActionController::Base
       include AccountHolderGate
       include BindingModuleGate
-      include WrongDoor
 
       prepend_before_action :refuse_unserved_binding
     end

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

@@ -8,11 +8,8 @@ module Kiosk
     class AssistantsController < ApplicationController
       SIGN_IN_PROMPT = 'Sign in to your account first to manage linked assistants.'
       SIGN_IN_ALERT  = 'Please sign in to manage your linked assistants.'
-
-      WRONG_DOOR_MESSAGE = "this is the account holder's browser page, not the Kiosk wire — " \
-                           'it needs a signed-in session and a CSRF token from its own form'
-
-      layout false
+      CAP_NOT_AN_AMOUNT   = 'Write the spending cap as an amount, such as 50 or 12.50.'
+      CURRENCY_NOT_A_CODE = 'Write the cap currency as a three-letter currency code, such as EUR.'
 
       def show
         return unless require_account_holder!(prompt: SIGN_IN_PROMPT, flash_alert: SIGN_IN_ALERT)
@@ -41,7 +38,7 @@ module Kiosk
         render_error(e)
       end
 
-      # Edits a bound assistant's label and/or spending cap and its currency (blank cap → unlimited).
+      # Edits a bound assistant's label and/or spending cap and its currency (blank cap → no cap).
       def update
         return unless require_account_holder!(prompt: SIGN_IN_PROMPT, flash_alert: SIGN_IN_ALERT)
 
@@ -62,8 +59,9 @@ module Kiosk
 
       def render_page(status: :ok)
         @assistants = LinkedAssistants.list(@identity.user_id)
-        # Without a `config.spending_cap` seam the saved cap binds nothing; the page says so.
-        @spending_cap_enforced = !Kiosk.configuration.spending_cap.nil?
+        # The spend shows where the origin takes payments; the cap, where a `spending_cap` reads it.
+        @payments     = !Kiosk.configuration.payment_provider.nil?
+        @spending_cap = !Kiosk.configuration.spending_cap.nil?
         @page_path = request.path.sub(%r{/(link|unlink|update)\z}, '')
         render :show, status: status
       end
@@ -72,24 +70,25 @@ module Kiosk
       def settings_changes
         changes = {}
         changes['human_label'] = params[:human_label].to_s if params.key?(:human_label)
-        changes['spending_cap_cents'], changes['spending_cap_currency'] = spending_cap_param if params.key?(:spending_cap_cents)
+        changes['spending_cap_cents'], changes['spending_cap_currency'] = spending_cap_param if params.key?(:spending_cap)
         changes
       end
 
-      # `[cents, currency]`, or `[nil, nil]` for no cap.
+      # `[cents, currency]` from the amount the person typed, or `[nil, nil]` for no cap.
       def spending_cap_param
-        raw = params[:spending_cap_cents].to_s
+        raw = params[:spending_cap].to_s
         return [nil, nil] if raw.strip.empty?
 
-        cents = Integer(raw, exception: false) || raise(Errors::BadRequest, 'spending_cap_cents must be an integer')
-        [cents, spending_cap_currency_param]
+        currency = spending_cap_currency_param
+        cents = Money.parse(raw, currency) || raise(Errors::BadRequest, CAP_NOT_AN_AMOUNT)
+        [cents, currency]
       end
 
       def spending_cap_currency_param
         code = MandateVerifier.canonical_currency(params[:spending_cap_currency])
         return code if MandateVerifier::CURRENCY_CODE.match?(code)
 
-        raise Errors::BadRequest, 'spending_cap_currency must be a three-letter ISO 4217 code, such as EUR'
+        raise Errors::BadRequest, CURRENCY_NOT_A_CODE
       end
     end
   end

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

@@ -5,8 +5,8 @@ require 'json'
 
 module Kiosk
   module Server
-    # The spec's challenge-response auth paths (§6), drawn by the engine: challenge, register, login,
-    # revoke, and the account-binding link, claim and unlink.
+    # The Kiosk auth paths that no OAuth standard covers (§5.7, §6), drawn by the
+    # engine: the key rotation, and the account-binding link, claim and unlink.
     class AuthController < ::ActionController::API
       # The JSON answers and RFC 9457 problem documents of the auth paths.
       module Answers
@@ -17,7 +17,7 @@ module Kiosk
           render json: payload, status: status
         end
 
-        # The same RFC 9457 problem document as the wire (§9).
+        # The same RFC 9457 problem document as the protocol (§9).
         def render_error(err)
           add_problem_headers(err)
           render json: err.to_problem, status: err.http_status,
@@ -32,12 +32,12 @@ module Kiosk
           response.set_header('WWW-Authenticate', challenge) if challenge
         end
 
-        # RFC 7235 challenge header for the 402s, as on the wire.
+        # RFC 7235 challenge header for the 402s, as in the protocol.
         def www_authenticate_for(err)
           issuer = Kiosk.current_issuer
           case err
           when Errors::PowRequired          then %(Kiosk-PoW realm="#{issuer}")
-          when Errors::PaymentSetupRequired then %(Payment realm="#{issuer}", method="ap2")
+          when Errors::PaymentSetupRequired then %(Kiosk-Payment-Setup realm="#{issuer}")
           end
         end
       end
@@ -61,52 +61,21 @@ module Kiosk
 
       prepend_before_action :refuse_unserved_binding, only: %i[link claim unlink]
 
-      # Unauthenticated: the nonce is worthless without the matching private key.
-      def challenge
-        public_key = request.query_parameters['public_key']
-        raise Errors::BadRequest, 'missing public_key query parameter' if public_key.blank?
+      # A refused client assertion is a 401, with the hint that says what to fix.
+      rescue_from(ClientAssertion::Refused) { |e| render_error(e.to_problem) }
 
-        respond(AuthChallenge.issue(public_key_pem: public_key), :ok)
-      rescue Errors::Base => e
-        render_error(e)
-      end
-
-      # Registers a new public key (409 if known). The optional PoW proof rides in the `Kiosk-PoW`
-      # header, so the signed body stays the same on retry.
-      def register
-        body   = parse_body!('POST <endpoint>/auth/register')
-        pow    = proofs
-        result = AgentRegistration.call(public_key_pem: body.fetch(:public_key), signed: body.fetch(:signed), pow: pow)
-        respond(result, :created)
+      # Puts a new key on a registered client; both keys sign (§5.7). Answers the client information.
+      def rotate
+        body   = parse_body!('POST <endpoint>/auth/rotate')
+        client = AgentRotation.call(type: body.fetch(:client_assertion_type), assertion: body.fetch(:client_assertion),
+                                    new_assertion: body.fetch(:new_client_assertion), jwks: body.fetch(:jwks))
+        respond(client.information, :ok)
       rescue KeyError => e
         render_error(Errors.missing_field(e))
       rescue Errors::Base => e
         render_error(e)
       end
 
-      # Refresh a token for an EXISTING public key (404 if unknown → register).
-      def login
-        body   = parse_body!('POST <endpoint>/auth/login')
-        result = AgentLogin.call(public_key_pem: body.fetch(:public_key), signed: body.fetch(:signed))
-        respond(result, :ok)
-      rescue KeyError => e
-        render_error(Errors.missing_field(e))
-      rescue Errors::Base => e
-        render_error(e)
-      end
-
-      # Revokes every token of the caller's agent and returns a fresh one.
-      def revoke
-        identity = authenticated_agent
-        raise Errors::Unauthenticated, 'agent authentication required' if identity.nil? || identity.agent_id.nil?
-
-        Kiosk.configuration.revocation_store.revoke_all(identity.agent_id, at: Time.now.to_i)
-        token = fresh_token(identity)
-        respond({ access_token: token }, :ok)
-      rescue Errors::Base => e
-        render_error(e)
-      end
-
       # Mints a link code for the signed-in holder; the holder's `user_idp` role becomes the bound assistant's.
       def link
         identity = authenticated_account_holder!
@@ -116,15 +85,14 @@ module Kiosk
         render_error(e)
       end
 
-      # §6.2's three fields only: `fresh` stays off the wire so a re-bind is indistinguishable (§6.3).
-      CLAIM_RESPONSE_FIELDS = %i[agent_id user_id access_token].freeze
-
-      # The optional PoW proof rides in the `Kiosk-PoW` header, as on register.
+      # Binds the client to the human who minted the code; answers 204. The
+      # optional toll's proofs ride in the `Kiosk-PoW` header.
       def claim
-        body   = parse_body!('POST <endpoint>/auth/claim')
-        result = LinkCode.redeem(code: body.fetch(:code), public_key_pem: body.fetch(:public_key),
-                                 signed: body.fetch(:signed), pow: proofs)
-        respond(result.slice(*CLAIM_RESPONSE_FIELDS), :created)
+        body = parse_body!('POST <endpoint>/auth/claim')
+        LinkCode.redeem(code: body.fetch(:code), assertion_type: body.fetch(:client_assertion_type),
+                        assertion: body.fetch(:client_assertion), pow: proofs)
+        Kiosk::Server::Headers.add_to(response.headers)
+        head :no_content
       rescue KeyError => e
         render_error(Errors.missing_field(e))
       rescue Errors::Base => e
@@ -146,29 +114,17 @@ module Kiosk
 
       private
 
-      # Auth endpoints always mint through the bundled DefaultAgentIdp.
-      def fresh_token(identity)
-        AgentIdentityProviders::DefaultAgentIdp.new.issue(agent_id: identity.agent_id, role: identity.role)
-      end
-
       # The human's side of binding authenticates by the provider's session, never by an agent token.
       # A page on another origin can post a form with that cookie, but cannot send JSON without a CORS preflight.
       def authenticated_account_holder!
         identity = Kiosk.configuration.user_idp&.verify(request)
         hint = "sign in to the provider first — this endpoint authenticates via the provider's own session"
-        raise Errors::Unauthenticated.new('account session required', hint:) unless identity
+        raise Errors::SessionRequired.new('account session required', hint:) unless identity
         raise Errors::BadRequest, 'Content-Type must be application/json' unless request.media_type == 'application/json'
 
         identity
       end
 
-      # nil for a missing, invalid or revoked bearer token.
-      def authenticated_agent
-        IdentityResolution.agent_idp.verify(request)
-      rescue Kiosk::Server::JwtIssuer::Error, Kiosk::AgentIdentityProviders::InvalidToken
-        nil
-      end
-
       # Schema-checked before any `fetch`, so a wrong-typed member is a 400 naming it (§17).
       def parse_body!(exchange)
         raw = request.raw_post

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

@@ -11,14 +11,9 @@ module Kiosk
 
       CODE_NOT_RECOGNISED = 'That code was not recognised — it may have expired. Ask the assistant for a fresh one.'
 
-      WRONG_DOOR_MESSAGE = "this is the account holder's browser consent page, not the Kiosk wire — " \
-                           'it needs a signed-in session and a CSRF token from its own form'
-
       # Failed code lookups per session before a 429, against 31^8 possible codes.
       MAX_CODE_ATTEMPTS = 10
 
-      layout false
-
       def show
         return unless require_account_holder!(prompt: SIGN_IN_PROMPT, flash_alert: SIGN_IN_ALERT)
         return render_attempts_capped if attempts_capped?

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

@@ -10,21 +10,33 @@ module Kiosk
       # Rails stamps `Vary: Accept` on a negotiated render; these documents are
       # one answer for everybody, so a shared cache must keep one copy.
       after_action :drop_vary
+      before_action :allow_cors
 
       def agents_txt
-        allow_cors
         render plain: WellKnown.agents_txt(base_url: request.base_url),
                content_type: 'text/plain; charset=utf-8'
       end
 
       def agents_json
-        allow_cors
         short_ttl
         render json: WellKnown.agents_json(base_url: request.base_url)
       end
 
-      def agent_configuration
-        render json: WellKnown.agent_configuration(base_url: request.base_url)
+      def oauth_authorization_server
+        render json: WellKnown.oauth_authorization_server(base_url: request.base_url)
+      end
+
+      def oauth_protected_resource
+        render json: WellKnown.oauth_protected_resource(base_url: request.base_url)
+      end
+
+      def agent_skills_index
+        render_or_not_found WellKnown.agent_skills_index
+      end
+
+      def ard
+        short_ttl
+        render json: WellKnown.ard(base_url: request.base_url)
       end
 
       def kiosk_json
@@ -33,22 +45,27 @@ module Kiosk
       end
 
       def api_catalog
-        allow_cors
         short_ttl
+        # RFC 9727 §2: a HEAD request finds the catalog by this header.
+        response.set_header('Link', %(<#{request.base_url}/.well-known/api-catalog>; rel="api-catalog"))
         render json: WellKnown.api_catalog(base_url: request.base_url),
                content_type: 'application/linkset+json; ' \
                              'profile="https://www.rfc-editor.org/info/rfc9727"'
       end
 
       def auth_md
-        allow_cors
         render plain: WellKnown.auth_md(base_url: request.base_url),
                content_type: 'text/markdown; charset=utf-8'
       end
 
       private
 
-      # agents.txt v1.0 requires `Access-Control-Allow-Origin: *`.
+      def render_or_not_found(document)
+        document ? render(json: document) : head(:not_found)
+      end
+
+      # agents.txt v1.0 and AI Catalog require `Access-Control-Allow-Origin: *`.
+      # Every document here answers it, so a page on any origin can read it.
       def allow_cors
         response.set_header('Access-Control-Allow-Origin', '*')
       end

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

@@ -4,11 +4,11 @@ require 'action_controller'
 
 module Kiosk
   module Server
-    # GET <endpoint>/.well-known/jwks.json — the public signing key.
+    # GET <endpoint>/.well-known/jwks.json — the current signing key, and the previous one while it is set.
     class JwksController < ::ActionController::API
       def show
         Kiosk::Server::Headers.add_to(response.headers)
-        render json: Kiosk::Server::Jwks.build(keys: [Kiosk.configuration.signing_key])
+        render json: Kiosk::Server::Jwks.build(keys: Kiosk.configuration.signing_keys)
       end
     end
   end

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

@@ -49,10 +49,7 @@ module Kiosk
 
       # Only an assistant submits an attestation, so only the agent IdP answers.
       def authenticate!
-        identity = IdentityResolution.agent_idp.verify(request)
-        raise Errors::Unauthenticated, 'missing or invalid agent token' if identity.nil?
-
-        identity
+        IdentityResolution.resolve(request) || raise(Errors::AccessTokenRefused)
       end
 
       def render_error(err)

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

@@ -7,7 +7,9 @@ module Kiosk
     class KycCallbackController < WireController
       def create
         Kyc.served!
-        Kyc.callback(parse_body!)
+        body = parse_body!
+        RequestValidation.validate_body!(body, exchange: 'POST <endpoint>/kyc/callback')
+        Kyc.callback(body)
         render json: { ok: true }, status: :ok
       end
     end

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

@@ -4,48 +4,36 @@ require 'action_controller'
 
 module Kiosk
   module Server
-    # POST <endpoint>/oauth/device_authorization (RFC 8628 §3.1): an assistant
-    # opens the claim half of account binding with `client_id` and `public_key`.
+    # POST <endpoint>/oauth/device_authorization (RFC 8628 §3.1): a registered
+    # client opens the claim half of account binding. It authenticates with a
+    # client assertion, so it sends no `client_id` of its own.
     class OauthDeviceAuthorizationController < ::ActionController::API
       include BindingModuleGate
+      include OauthAnswers
 
       prepend_before_action :refuse_unserved_binding
 
       def create
-        problem = request_problem
-        return render_oauth_error(:invalid_request, problem, status: 400) if problem
+        problem = role_problem
+        raise OauthError.new(:invalid_request, problem) if problem
 
-        result = DeviceCodeGrant.start(client_id: params[:client_id].to_s, public_key_pem: params[:public_key].to_s)
-        Kiosk::Server::Headers.add_to(response.headers)
-        render json: device_authorization(result)
+        render_oauth(device_authorization(DeviceCodeGrant.start(client: authenticate_client!)))
+      rescue OauthError => e
+        render_oauth_error(e)
       end
 
       private
 
-      # The first reason this request is refused, or nil.
-      def request_problem
-        return 'client_id parameter required' if params[:client_id].to_s.empty?
-        return 'public_key parameter required' if params[:public_key].to_s.empty?
-
-        key_problem(params[:public_key].to_s) || role_problem
-      end
-
-      def key_problem(public_key)
-        PopVerifier.load_public_key(public_key.strip)
-        nil
-      rescue Errors::BadRequest => e
-        e.message
-      end
-
-      # Refused, not ignored: the role is the approving human's, and this
-      # request is unauthenticated.
+      # A `role` is refused: the role is the approving human's, and the
+      # assistant does not choose it. A `scope` is ignored (RFC 6749 Section
+      # 3.3): an assistant gets another role only when a human who holds that
+      # role binds it to their account, or through the identity provider.
       def role_problem
-        offending = %i[role scope].find { |name| params.key?(name) }
-        return unless offending
+        return unless params.key?(:role)
 
-        "#{offending} is not accepted here — an assistant does not choose its own role. " \
-          "The role of a bound assistant is the approving account holder's own role, " \
-          "read from this provider's identity system when they approve at the verify page."
+        'role is not accepted here: an assistant does not choose its own role. ' \
+          'The role of a bound assistant is the role of the account holder who approves, ' \
+          "and this provider's identity system gives it at the verify page."
       end
 
       def device_authorization(result)
@@ -63,11 +51,6 @@ module Kiosk
         mount = Kiosk.configuration.mount_path
         "#{request.base_url}#{mount}/oauth/device/verify"
       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
-      end
     end
   end
 end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+require 'json'
+
+module Kiosk
+  module Server
+    # POST <endpoint>/oauth/register (RFC 7591 Section 3): open registration of
+    # an AI assistant's public key. The optional toll's proofs ride in the
+    # `Kiosk-PoW` header, so the body stays the same on retry.
+    class OauthRegistrationController < ::ActionController::API
+      include AuthController::Answers
+      include AuthController::Proofs
+      include OauthAnswers
+
+      def create
+        client = ClientRegistration.call(metadata, pow: proofs)
+        render_oauth(client.information, status: :created)
+      rescue OauthError => e
+        render_oauth_error(e)
+      rescue Errors::Base => e
+        render_error(e)
+      end
+
+      private
+
+      def metadata
+        JSON.parse(request.raw_post.to_s)
+      rescue JSON::ParserError
+        raise OauthError.new(:invalid_client_metadata, 'the request body must be a JSON object')
+      end
+    end
+  end
+end