kiosk-server 0.5.20

data/lib/kiosk/server/pow_spent_stores.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Stores for the PoW spent-id set (`config.pow_spent_store`). A store
+    # answers `claim(id, exp)` (atomic: true iff this caller claimed it),
+    # `release(id)`, `spent?(id)` and `mark_spent(id, exp)`.
+    module PowSpentStores
+      # The default store: the `<schema>.pow_spent` table, shared by every process.
+      class ActiveRecord
+        # The sweep bounds table growth; correctness does not depend on it.
+        DEFAULT_PRUNE_INTERVAL = 60
+
+        def initialize(prune_interval: DEFAULT_PRUNE_INTERVAL)
+          @prune_interval = prune_interval
+          @last_prune_at  = 0
+          @mutex          = Mutex.new
+        end
+
+        # One statement: the primary key picks the winner; an expired row is reclaimable.
+        def claim(id, exp) # rubocop:disable Naming/PredicateMethod -- `claim` is the store contract `config.pow_spent_store` names
+          return false if id.nil?
+
+          prune_if_due!
+          rows = connection.exec_query(claim_sql, 'Kiosk pow_spent claim', [id, exp.to_i]).to_a
+          !rows.empty?
+        end
+
+        def release(id)
+          return if id.nil?
+
+          connection.exec_query(%(DELETE FROM #{table} WHERE id = $1), 'Kiosk pow_spent release', [id])
+          nil
+        end
+
+        def spent?(id)
+          return false if id.nil?
+
+          sql = <<~SQL.squish
+            SELECT 1 FROM #{table}
+            WHERE id = $1 AND expires_at > now()
+            LIMIT 1
+          SQL
+          row = connection.exec_query(sql, 'Kiosk pow_spent lookup', [id]).to_a.first
+          !row.nil?
+        end
+
+        def mark_spent(id, exp)
+          return if id.nil?
+
+          sql = <<~SQL.squish
+            INSERT INTO #{table} (id, expires_at)
+            VALUES ($1, to_timestamp($2))
+            ON CONFLICT (id) DO UPDATE SET expires_at = EXCLUDED.expires_at
+          SQL
+          connection.exec_query(sql, 'Kiosk pow_spent mark', [id, exp.to_i])
+          nil
+        end
+
+        def prune!
+          connection.exec_query(%(DELETE FROM #{table} WHERE expires_at <= now()), 'Kiosk pow_spent prune')
+          nil
+        end
+
+        private
+
+        def claim_sql
+          <<~SQL.squish
+            INSERT INTO #{table} AS s (id, expires_at)
+            VALUES ($1, to_timestamp($2))
+            ON CONFLICT (id) DO UPDATE
+              SET expires_at = EXCLUDED.expires_at
+              WHERE s.expires_at <= now()
+            RETURNING s.id
+          SQL
+        end
+
+        def prune_if_due!
+          now = Time.now.to_i
+          due = @mutex.synchronize do
+            if now - @last_prune_at >= @prune_interval
+              @last_prune_at = now
+              true
+            else
+              false
+            end
+          end
+          prune! if due
+        end
+
+        def connection = ::ActiveRecord::Base.lease_connection
+        def table = %("#{Kiosk.configuration.schema}".pow_spent)
+      end
+    end
+  end
+end

data/lib/kiosk/server/pow_toll.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # One proof-of-work toll on one request: `count` distinct, unspent, valid
+    # proofs, or the error that sends the caller back. Shared by
+    # {PowGate.gate} and {AuthToll}.
+    class PowToll
+      def initialize(spec:, fingerprint:, secret:, config:)
+        @spec         = spec
+        @fingerprint  = fingerprint
+        @secret       = secret
+        @config       = config
+      end
+
+      # Returns `:proceed`, or raises PowRequired (402), BadRequest or Forbidden.
+      def collect!(pow)
+        validate_spec_params!
+        submitted = Array(pow)
+        raise pow_required if submitted.empty?
+
+        accepted = accept_all(submitted)
+        return :proceed if accepted.size >= count
+
+        # Released, so the retry with fresh challenges is not blocked by our own claim.
+        accepted.each_key { |id| spent_store.release(id) }
+        raise pow_required
+      end
+
+      private
+
+      # `count` distinct, unspent, valid proofs; one wrong proof is a 403.
+      # Proofs past `count` are not looked at, so a header cannot buy extra work.
+      def accept_all(submitted)
+        submitted.first(count).each_with_object({}) { |proof, accepted| accept(proof, accepted) }
+      end
+
+      def accept(proof, accepted)
+        challenge = proof[:challenge].is_a?(Hash) ? proof[:challenge] : {}
+        return unless claimed?(challenge, accepted)
+
+        settle(verify(challenge, proof[:nonce]), challenge, accepted)
+      end
+
+      # The cheap checks first, so only a live challenge this origin signed
+      # claims its id, at the `exp` it was signed with; the claim comes before
+      # the expensive verify. A lost claim is a replay: skipped, not penalised.
+      def claimed?(challenge, accepted)
+        id = challenge[:id]
+        return false if id.nil? || accepted.key?(id)
+
+        check_challenge_params!(challenge)
+        cheap_failure(challenge).nil? && spent_store.claim(id, challenge[:exp])
+      end
+
+      def cheap_failure(challenge)
+        ::Kiosk::Reputation::Challenge.check(
+          challenge: challenge, request_fingerprint: @fingerprint, secret: @secret,
+          now: Time.now.to_i, expect: { alg: alg, params: params }
+        )
+      end
+
+      def check_challenge_params!(challenge)
+        return if challenge[:params].is_a?(Hash)
+
+        raise Errors::BadRequest.new(
+          'malformed PoW proof: challenge.params is missing or not an object',
+          hint: PowGate::POW_HEADER_HINT
+        )
+      end
+
+      # `expect`: honoured only at the difficulty live config demands now.
+      def verify(challenge, nonce)
+        ::Kiosk::Reputation::Challenge.verify(
+          challenge: challenge, nonce: nonce, request_fingerprint: @fingerprint,
+          secret: @secret, now: Time.now.to_i, expect: { alg: alg, params: params }
+        )
+      end
+
+      def settle(outcome, challenge, accepted)
+        case outcome
+        when :ok
+          accepted[challenge[:id]] = challenge[:exp].to_i
+        when :bad_proof
+          # The id stays consumed, so one challenge drives at most one verify.
+          raise Errors::Forbidden.new('invalid proof of work', hint: PowGate::POW_INVALID_HINT)
+        when :expired, :bad_sig, :bad_params
+          # Not bad faith (clock skew, a difficulty change): release the claim
+          # and re-challenge below.
+          spent_store.release(challenge[:id])
+        end
+      end
+
+      def validate_backend!
+        return if ::Kiosk::Reputation::Backends.known.include?(alg.to_s)
+
+        raise Errors::ConfigurationError,
+              "Kiosk::Server: no proof-of-work backend is registered for #{alg.to_s.inspect}. " \
+              "Register one: Kiosk::Reputation::Backends.register(#{alg.to_s.inspect}, backend)."
+      end
+
+      def validate_spec_params!
+        validate_backend!
+        return if ::Kiosk::Reputation::Backends.valid_params?(alg, params)
+
+        raise Errors::ConfigurationError,
+              "Kiosk::Server: the #{alg.to_s.inspect} proof-of-work backend refuses the configured " \
+              "parameters #{params.inspect} — no proof solved at them could ever verify, so every " \
+              'honest client would be told its correct proof was invalid. Fix the `params:` ' \
+              'your reputation_policy returns from #challenge_for.'
+      end
+
+      # Equihash has no difficulty dial: escalation is by proof count.
+      def count
+        [(@spec[:count] || 1).to_i, 1].max
+      end
+
+      # TTL scales with `count`, so the first expires no sooner than the last is solved.
+      def pow_required
+        ttl = @config.pow_ttl * count
+        Errors::PowRequired.new(challenges: Array.new(count) { issue_challenge(ttl) })
+      end
+
+      def issue_challenge(ttl)
+        ::Kiosk::Reputation::Challenge.issue(
+          alg: alg, params: params, request_fingerprint: @fingerprint,
+          secret: @secret, ttl: ttl, now: Time.now.to_i
+        )
+      end
+
+      def alg    = @spec[:alg]
+      def params = @spec[:params]
+      def spent_store = @config.pow_spent_store
+    end
+  end
+end

data/lib/kiosk/server/queries.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The query registry (`kind :query`); everything else is {VerbRegistry}.
+    # Read-only is a convention the provider upholds (the registry does not enforce it).
+    module Queries
+      SCOPE = :query
+      Entry = VerbRegistry::Entry
+
+      extend VerbRegistry
+    end
+  end
+end

data/lib/kiosk/server/reputation_factors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+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.
+    module ReputationFactors
+      module_function
+
+      # Empty factors unless the policy names a window (`#within`, in seconds).
+      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)
+      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.
+      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
+
+      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
+            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
+        ) spend
+      SQL
+    end
+  end
+end

data/lib/kiosk/server/request_validation.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Validates requests against the vendored normative schemas: `Kiosk-PoW`
+    # proofs and reserved-plane bodies behind `c.validate_requests` (§16.3), and
+    # verb arguments against their `input_schema` always (§8.1 item 5).
+    module RequestValidation
+      module_function
+
+      SCHEMA_DIR = File.expand_path('schemas', __dir__)
+
+      POW_SCHEMA_PATH = File.join(SCHEMA_DIR, 'pow.schema.json')
+
+      # RESERVED-PLANE REQUEST BODY => the published object that types it.
+      # The `/oauth/*` requests are form-encoded and have no schema.
+      BODY_SCHEMAS = {
+        'POST <endpoint>/auth/register' => 'auth.schema.json#/$defs/credentialRequest',
+        'POST <endpoint>/auth/login' => 'auth.schema.json#/$defs/credentialRequest',
+        '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>/pay' => 'mandates.schema.json#/$defs/payRequest'
+      }.freeze
+
+      def validate_proofs!(proofs)
+        Array(proofs).each do |proof|
+          errors = Schemas.proof.validate(normalize(proof)).to_a
+          next if errors.empty?
+
+          raise Errors::BadRequest.new(
+            'malformed Kiosk-PoW proof',
+            hint: POW_SHAPE_HINT
+          )
+        end
+      end
+
+      # A missing member keeps the wire's own `missing field:` sentence.
+      def validate_body!(body, exchange:)
+        return unless Kiosk.configuration.validate_requests
+
+        pointer = BODY_SCHEMAS.fetch(exchange)
+        errors  = Schemas.wire(pointer).validate(normalize(body)).to_a
+        return if errors.empty?
+
+        absent = missing_member(errors, body)
+        raise Errors.missing_field(absent, hint: body_hint(pointer)) if absent
+
+        raise Errors::BadRequest.new("#{exchange}: #{summary(errors)}", hint: body_hint(pointer))
+      end
+
+      def missing_member(errors, body)
+        return nil unless errors.any? { |error| error['type'] == 'required' }
+
+        present = normalize(body).keys
+        errors.filter_map { |error| error['details']&.fetch('missing_keys', nil) }
+              .flatten.find { |name| present.exclude?(name) }
+      end
+
+      def body_hint(pointer)
+        file, fragment = pointer.split('#', 2)
+        "the body must satisfy #{file} #{fragment}, published at " \
+          "https://kiosk.tech/spec/schemas/#{file}."
+      end
+
+      # Runs on the coerced arguments. On a query an undeclared `limit`/`cursor`
+      # is exempt: a query always accepts those names (§8.1 item 6). An action
+      # has no pages, so its body is held to its input_schema with no exemption.
+      def validate_arguments!(arguments, input_schema:, verb:, query:)
+        return if input_schema.nil?
+
+        require_schemer!
+        exempt  = query ? ArgumentDecoder::RESERVED.keys - declared_property_names(input_schema) : []
+        payload = normalize(arguments).except(*exempt)
+        errors  = JSONSchemer.schema(normalize(input_schema)).validate(payload).to_a
+        return if errors.empty?
+
+        raise Errors::BadRequest.new("#{verb}: #{summary(errors)}", hint: arguments_hint(errors))
+      end
+
+      def arguments_hint(errors)
+        "#{format_spellings(errors)}GET <endpoint>/schema publishes this verb's input_schema; the " \
+          'arguments must satisfy it. A query also accepts `limit` and `cursor`.'
+      end
+
+      def summary(errors) = errors.pluck('error').compact.join('; ')
+
+      # What to send for each argument that failed its declared `format`.
+      def format_spellings(errors)
+        errors.filter_map do |error|
+          next unless error['type'] == 'format'
+
+          spelling = ArgumentDecoder::FORMAT_SPELLINGS[error.dig('schema', 'format')]
+          "#{error['data_pointer'].delete_prefix('/')}: send #{spelling}. " if spelling
+        end.uniq.join
+      end
+
+      def declared_property_names(input_schema)
+        properties = ArgumentDecoder.fetch(input_schema, :properties)
+        properties.is_a?(Hash) ? properties.keys.map(&:to_s) : []
+      end
+
+      # The nonce is named relative to `alg`: its shape depends on the backend.
+      POW_SHAPE_HINT =
+        'each Kiosk-PoW proof = ' \
+        '{challenge: <the challenge object from the 402, echoed verbatim>, ' \
+        "nonce: <the solution, in the shape the challenge's `alg` defines — " \
+        'for equihash, {indices: […], header_nonce?}>}; the header carries one proof as ' \
+        'raw JSON or a JSON array of proofs. ' \
+        'Solve each challenge issued in the pow_required 402 and echo it back verbatim.'
+
+      def reset! = Schemas.reset!
+
+      # The vendored schemas, parsed once.
+      module Schemas
+        module_function
+
+        def proof
+          @proof ||= build_proof
+        end
+
+        # Rooted at one `$def`, with the file's other `$defs` in scope.
+        def wire(pointer)
+          @wire ||= {}
+          @wire[pointer] ||= begin
+            RequestValidation.require_schemer!
+            file, fragment = pointer.split('#', 2)
+            doc = JSON.parse(File.read(File.join(SCHEMA_DIR, file)))
+            JSONSchemer.schema(doc.merge('$ref' => "##{fragment}"))
+          end
+        end
+
+        def reset!
+          @proof = nil
+          @wire = nil
+        end
+
+        def build_proof
+          RequestValidation.require_schemer!
+          doc = JSON.parse(File.read(POW_SCHEMA_PATH))
+          root = doc.merge('$ref' => '#/$defs/proof')
+          root.delete('oneOf')
+          JSONSchemer.schema(root)
+        end
+      end
+
+      def require_schemer!
+        require 'json_schemer'
+      rescue LoadError
+        raise Errors::ConfigurationError,
+              'Kiosk::Server: validate_requests is enabled but the json_schemer gem ' \
+              'is not loadable. It is a RUNTIME dependency of kiosk-server ' \
+              'and should already be in your lockfile — check that the bundle is ' \
+              'installed and not pruned (`bundle install`, or `bundle list | grep ' \
+              'json_schemer`); add `gem "json_schemer"` to your Gemfile only if you ' \
+              'load kiosk-server outside Bundler.'
+      end
+
+      def normalize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_s] = normalize(v) }
+        when Array
+          obj.map { |v| normalize(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/response_validation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # With `c.validate_responses`, checks every verb's answer against its own
+    # `output_schema` and fails loudly on a mismatch. Off by default: in
+    # production a descriptor typo would become a 500 for an innocent caller.
+    module ResponseValidation
+      module_function
+
+      def validate_payload!(payload, output_schema:, verb:, kind:)
+        return if output_schema.nil?
+
+        RequestValidation.require_schemer!
+        schemer = JSONSchemer.schema(RequestValidation.normalize(output_schema))
+        errors  = schemer.validate(RequestValidation.normalize(payload)).to_a
+        return if errors.empty?
+
+        raise Errors::ActionFailed.new(
+          "#{kind} #{verb.inspect} rendered a payload its own output_schema rejects: " \
+          "#{summarise(errors)}",
+          hint: mismatch_hint(verb)
+        )
+      end
+
+      def mismatch_hint(verb)
+        "the descriptor and the handler disagree — `#{verb}` publishes an " \
+          'output_schema that its rendered answer does not satisfy. Fix whichever ' \
+          'is wrong; a published schema an assistant cannot rely on is worse than ' \
+          'none. (Kiosk.configuration.validate_responses is on.)'
+      end
+
+      MAX_REPORTED = 5
+
+      def summarise(errors)
+        reported = errors.first(MAX_REPORTED).map do |error|
+          pointer = error['data_pointer'].to_s
+          "#{pointer.empty? ? '(root)' : pointer}: #{error['error']}"
+        end
+        reported << "(#{errors.length - MAX_REPORTED} more)" if errors.length > MAX_REPORTED
+        reported.join('; ')
+      end
+    end
+  end
+end

data/lib/kiosk/server/result.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The executor's internal carrier for a successful call; only {#to_payload}
+    # reaches the wire, as the body.
+    class Result < Data.define(:kind, :payload, :next_cursor, :total)
+      KINDS = %i[rows value].freeze
+
+      def initialize(kind:, payload:, next_cursor: nil, total: nil)
+        kind = kind.to_sym
+        raise ArgumentError, "kind must be one of #{KINDS.inspect}, got #{kind.inspect}" unless KINDS.include?(kind)
+        raise ArgumentError, "next_cursor is only valid on a :rows result (got #{kind.inspect})" if next_cursor && kind != :rows
+        raise ArgumentError, "total is only valid on a :rows result (got #{kind.inspect})" if total && kind != :rows
+
+        super
+      end
+
+      def http_status = 200
+
+      # Verbatim, with no envelope; a page's facts travel as headers (§8.2, §8.4).
+      def to_payload = payload
+    end
+  end
+end

data/lib/kiosk/server/revocation_stores.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Stores for `config.revocation_store`. A store answers
+    # `revoke_all(agent_id, at:)`, `watermark_for(agent_id)` and
+    # `revoked?(agent_id:, iat:)`: a token whose `iat` is strictly before the
+    # agent's watermark is revoked.
+    module RevocationStores
+      # The default store: the `<schema>.revocations` table, shared by every
+      # process and kept across restarts. A token of an unlinked or deleted
+      # agent is revoked too.
+      class ActiveRecord
+        # The watermark only moves forward.
+        def revoke_all(agent_id, at:)
+          return if agent_id.nil?
+
+          connection.exec_query(<<~SQL.squish, 'Kiosk revocation', [agent_id, at.to_i])
+            INSERT INTO #{table('revocations')} AS r (agent_id, revoked_before)
+            VALUES ($1, to_timestamp($2))
+            ON CONFLICT (agent_id) DO UPDATE
+              SET revoked_before = GREATEST(r.revoked_before, EXCLUDED.revoked_before)
+          SQL
+          nil
+        end
+
+        def watermark_for(agent_id)
+          return nil if agent_id.nil?
+
+          row = connection.exec_query(<<~SQL.squish, 'Kiosk revocation watermark', [agent_id]).to_a.first
+            SELECT extract(epoch FROM revoked_before)::bigint AS at
+            FROM #{table('revocations')} WHERE agent_id = $1
+          SQL
+          row&.fetch('at')
+        end
+
+        def revoked?(agent_id:, iat:)
+          return false if agent_id.nil? || iat.nil?
+
+          connection.exec_query(<<~SQL.squish, 'Kiosk revocation check', [agent_id, iat.to_i]).to_a.empty?
+            SELECT 1
+            FROM #{table('agents')} a
+            LEFT JOIN #{table('revocations')} r ON r.agent_id = a.id
+            WHERE a.id = $1
+              AND a.revoked_at IS NULL
+              AND (r.revoked_before IS NULL OR r.revoked_before <= to_timestamp($2))
+          SQL
+        end
+
+        private
+
+        def connection = ::ActiveRecord::Base.lease_connection
+        def table(name) = %("#{Kiosk.configuration.schema}".#{name})
+      end
+    end
+  end
+end

data/lib/kiosk/server/routing.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'action_dispatch/routing'
+
+module Kiosk
+  module Server
+    # `kiosk do … end` in config/routes.rb. Mounts the engine at the configured
+    # mount_path first, so the protocol plane wins by first match, then draws
+    # GET <mount_path>/<name> for each query and POST for each action, each to
+    # the controller action that declares the verb.
+    #
+    #   kiosk do
+    #     queries :catalog
+    #     actions :place_order
+    #   end
+    module Routing
+      def kiosk(&block)
+        mount Kiosk::Server::Engine => Kiosk.configuration.mount_path
+        Verbs.new(self).instance_exec(&block) if block
+      end
+
+      # The block's receiver: a query or an action are the only verbs there are.
+      class Verbs
+        def initialize(mapper)
+          @mapper = mapper
+        end
+
+        def queries(*names) = draw(:get, :query, names)
+        def actions(*names) = draw(:post, :action, names)
+
+        private
+
+        def draw(method, kind, names)
+          names.each do |name|
+            @mapper.public_send(method, "#{Kiosk.configuration.mount_path}/#{name}", to: VerbRoute.new(kind, name.to_s))
+          end
+        end
+      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
+      # development reload is served. A name that no action answers goes to
+      # {VerbController}, which refuses it.
+      class VerbRoute
+        attr_reader :kind, :name
+
+        def initialize(kind, name)
+          @kind = kind
+          @name = name
+        end
+
+        def call(env)
+          controller, action, extra = target
+          env[HandlerServing::VERB_KEY] = @name
+          env['action_dispatch.request.path_parameters'] = { controller: controller.controller_path, action: action, **extra }
+          controller.action(action).call(env)
+        end
+
+        # The action this route reaches now, as `controller#action`; `bin/rails routes` prints it.
+        def endpoint = target.then { |controller, action| "#{controller.controller_path}##{action}" }
+        alias inspect endpoint
+
+        private
+
+        def target
+          registry = HandlerMixin.registry_for(@kind)
+          handler  = registry.fetch(@name) if registry.known.include?(@name)
+          controller = handler.controller if handler.is_a?(ControllerVerb)
+          return [controller, handler.method_name, {}] if controller
+
+          [VerbController, @kind == :query ? 'show' : 'create', { kiosk_verb: @name }]
+        end
+      end
+    end
+  end
+end