kiosk-server 0.5.20

data/lib/kiosk/server/settled_spend.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # What an assistant spent: each settlement less what was refunded of it,
+    # never below zero, one tally per currency. The «Link an assistant» page
+    # shows this figure. The spending cap counts it plus the carts in flight.
+    module SettledSpend
+      module_function
+
+      # The net cents of the current `settlements` row.
+      def net_cents_sql(schema)
+        <<~SQL.squish
+          GREATEST(settlements.settled_amount_cents - (
+            SELECT COALESCE(SUM(r.refunded_amount_cents), 0) FROM #{schema}.refunds r WHERE r.settlement_id = settlements.id
+          ), 0)
+        SQL
+      end
+    end
+  end
+end

data/lib/kiosk/server/signing_key.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'digest'
+require 'json'
+
+module Kiosk
+  module Server
+    # The RSA key that signs this deployment's JWTs, and its public JWK.
+    class SigningKey
+      MIN_KEY_BITS = 2048
+
+      ALGORITHM = 'RS256'
+
+      attr_reader :rsa
+
+      def initialize(rsa)
+        raise ArgumentError, "expected OpenSSL::PKey::RSA, got #{rsa.class}" unless rsa.is_a?(OpenSSL::PKey::RSA)
+        if rsa.n.num_bits < MIN_KEY_BITS
+          raise ArgumentError,
+                "RSA key is #{rsa.n.num_bits} bits; minimum is #{MIN_KEY_BITS}"
+        end
+        @rsa = rsa
+      end
+
+      def self.generate(bits: MIN_KEY_BITS)
+        new(OpenSSL::PKey::RSA.generate(bits))
+      end
+
+      # A public-only PEM verifies; a full keypair also signs.
+      def self.from_pem(pem)
+        new(OpenSSL::PKey::RSA.new(pem))
+      end
+
+      delegate :public_key, to: :rsa
+
+      delegate :private?, to: :rsa
+
+      def to_pem
+        raise 'cannot export PEM: signing key is public-only' unless private?
+
+        rsa.to_pem
+      end
+
+      # The RFC 7638 thumbprint.
+      def kid
+        @kid ||= compute_thumbprint
+      end
+
+      # RFC 7517 §4; never the private parameters.
+      def to_jwk
+        {
+          kty: 'RSA',
+          use: 'sig',
+          alg: ALGORITHM,
+          kid: kid,
+          n: b64url(rsa.n.to_s(2)),
+          e: b64url(rsa.e.to_s(2))
+        }
+      end
+
+      private
+
+      def compute_thumbprint
+        # RFC 7638 §3.2: the required members, in alphabetical order.
+        canonical = JSON.generate(
+          {
+            e: b64url(rsa.e.to_s(2)),
+            kty: 'RSA',
+            n: b64url(rsa.n.to_s(2))
+          }
+        )
+        b64url(Digest::SHA256.digest(canonical))
+      end
+
+      def b64url(bytes)
+        Base64.urlsafe_encode64(bytes, padding: false)
+      end
+    end
+  end
+end

data/lib/kiosk/server/verb_registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # A verb registry: name → handler plus the descriptor an origin publishes.
+    # {Queries} and {Actions} are this module plus a `SCOPE`. Verbs are declared
+    # through {Kiosk::Handler}; `input_schema` and `output_schema` are required (§8.3).
+    module VerbRegistry
+      Entry = Data.define(:handler, :reach, :description, :input_schema, :output_schema,
+                          :example_params, :example_row)
+
+      class << self
+        # Undeclared optional keys are omitted rather than null.
+        def add_declared_slots(descriptor, found)
+          descriptor[:input_schema]   = found.input_schema   unless found.input_schema.nil?
+          descriptor[:output_schema]  = found.output_schema  unless found.output_schema.nil?
+          descriptor[:example_params] = found.example_params unless found.example_params.nil?
+          descriptor[:example_row]    = found.example_row    unless found.example_row.nil?
+          descriptor
+        end
+      end
+
+      # @api private — the {HandlerMixin} is the only caller.
+      # `slots`: any of {SchemaSlots::RESOLVABLE_SLOTS}; an undeclared one is nil.
+      def declare(name, handler, reach: HandlerMixin::DEFAULT_REACH, description: nil, **slots)
+        slots = SchemaSlots::RESOLVABLE_SLOTS.index_with(nil).merge(slots)
+        entry = Entry.new(handler: handler, reach: reach, description: description, **slots)
+        SchemaSlots.note_declaration(slots)
+        registry[name.to_s] = entry
+      end
+
+      def fetch(name)
+        entry(name).handler
+      end
+
+      def describe(name)
+        found = entry(name)
+        SchemaSlots.descriptor(self::SCOPE, name, found) do
+          descriptor = { name: name.to_s, description: found.description, reach: found.reach.to_s }
+          VerbRegistry.add_declared_slots(descriptor, found)
+        end
+      end
+
+      def catalog
+        registry.keys.sort.map { |name| describe(name) }
+      end
+
+      def known
+        registry.keys
+      end
+
+      def unregister(name)
+        registry.delete(name.to_s)
+      end
+
+      def reset!
+        @registry = nil
+      end
+
+      private
+
+      # The 404's hint lists the registered names, already public via `/schema`.
+      def entry(name)
+        registry.fetch(name.to_s) do
+          raise Errors::VerbNotFound.new(
+            "Unknown #{self::SCOPE}: #{name.inspect}",
+            hint: Errors.unknown_name_hint(name, self::SCOPE.to_s, registry.keys.sort)
+          )
+        end
+      end
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/kiosk/server/verb_vocabulary.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # A policy hook is asked about writes as `:run` (§13), never `:action`, and
+    # a branch on `:action` would silently toll nothing. Refuses one at load by
+    # parsing the hook's source; returns `:unreadable` when it cannot.
+    module VerbVocabulary
+      WRITE_KIND = :run
+
+      DECLARATION_ALIAS = :action
+
+      COMPARISONS = %i[== != eql? equal?].freeze
+
+      def self.assert!(target, method_name, label)
+        location = HookSource.location_for(target, method_name)
+        return :unreadable if location.nil?
+
+        node = HookSource.node_at(*location)
+        return :unreadable if node.nil?
+
+        return :clean unless alias_branch?(node)
+
+        raise Errors::ConfigurationError, alias_branch_message(label, *location)
+      end
+
+      def self.alias_branch_message(label, file, line)
+        "Kiosk::Server: #{label} branches on :#{DECLARATION_ALIAS}, which this hook never " \
+          "receives (#{file}:#{line}). The gate hands it one of " \
+          "Kiosk::Server::Executor::VERBS — #{Executor::VERBS.map(&:inspect).join(', ')} — in which a " \
+          "handler declared `kind :#{DECLARATION_ALIAS}` arrives as :#{WRITE_KIND}. Branch on " \
+          ":#{WRITE_KIND}. (Protocol Section 13, Reputation.) A branch on :#{DECLARATION_ALIAS} " \
+          'would match nothing and silently decline to toll every write.'
+      end
+      private_class_method :alias_branch_message
+
+      def self.alias_branch?(node)
+        found = false
+        HookSource.walk(node) do |candidate|
+          next if found
+
+          found = true if comparison_against_alias?(candidate) ||
+                          when_clause_against_alias?(candidate) ||
+                          inclusion_against_alias?(candidate)
+        end
+        found
+      end
+      private_class_method :alias_branch?
+
+      def self.comparison_against_alias?(node)
+        return false unless node.is_a?(Prism::CallNode)
+        return false unless COMPARISONS.include?(node.name)
+
+        operands = [node.receiver, *(node.arguments&.arguments || [])]
+        operands.any? { |operand| alias_literal?(operand) }
+      end
+      private_class_method :comparison_against_alias?
+
+      def self.when_clause_against_alias?(node)
+        return false unless node.is_a?(Prism::WhenNode)
+
+        node.conditions.any? { |condition| alias_literal?(condition) }
+      end
+      private_class_method :when_clause_against_alias?
+
+      def self.inclusion_against_alias?(node)
+        return false unless node.is_a?(Prism::CallNode)
+        return false unless %i[include? member? exclude?].include?(node.name)
+
+        inclusion_candidates(node).any? { |candidate| alias_literal?(candidate) }
+      end
+      private_class_method :inclusion_against_alias?
+
+      # The receiver's array elements, then each argument and its array elements.
+      def self.inclusion_candidates(node)
+        candidates = node.receiver.is_a?(Prism::ArrayNode) ? node.receiver.elements.dup : []
+        (node.arguments&.arguments || []).each do |argument|
+          candidates.concat(argument.elements) if argument.is_a?(Prism::ArrayNode)
+          candidates << argument
+        end
+        candidates
+      end
+      private_class_method :inclusion_candidates
+
+      def self.alias_literal?(node)
+        case node
+        when Prism::SymbolNode, Prism::StringNode
+          node.unescaped == DECLARATION_ALIAS.to_s
+        else
+          false
+        end
+      end
+      private_class_method :alias_literal?
+
+      # Finds a hook's source and parses it; every answer is nil when it cannot.
+      module HookSource
+        module_function
+
+        def location_for(target, method_name)
+          callable = callable_for(target, method_name)
+          return nil unless callable.respond_to?(:source_location)
+
+          readable_location(callable.source_location)
+        end
+
+        def callable_for(target, method_name)
+          target.method(method_name) if target.respond_to?(method_name)
+        end
+
+        # `[file, line]` when the file can be read.
+        def readable_location(location)
+          return nil unless location.is_a?(Array) && location[0].is_a?(String) && location[1].is_a?(Integer)
+
+          location if File.readable?(location[0])
+        end
+
+        # The widest construct starting on the hook's source line.
+        def node_at(file, line)
+          tree = parse(file)
+          return nil if tree.nil?
+
+          best = nil
+          walk(tree) do |node|
+            next unless node.location.start_line == line
+            next if best && node.location.end_line <= best.location.end_line
+
+            best = node
+          end
+          best
+        end
+
+        def parse(file)
+          @parsed ||= {}
+          key = [file, mtime_of(file)]
+          return @parsed[key] if @parsed.key?(key)
+
+          @parsed[key] = parse_tree(file)
+        end
+
+        def mtime_of(file)
+          File.mtime(file)
+        rescue StandardError
+          nil
+        end
+
+        def parse_tree(file)
+          require 'prism'
+          result = Prism.parse_file(file)
+          result.success? ? result.value : nil
+        rescue LoadError, StandardError
+          nil
+        end
+
+        def walk(node, &block)
+          return if node.nil?
+
+          block.call(node)
+          node.compact_child_nodes.each { |child| walk(child, &block) }
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/verb_wire.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Kiosk
+  module Server
+    # The gates of a call on the wire, 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.
+    module VerbWire
+      include WireRendering
+
+      BODY_HINT = "an action's arguments are a JSON object in the request body; " \
+                  "a query's are in the query string."
+
+      private
+
+      def resolve_identity!
+        identity = IdentityResolution.resolve(request)
+        raise Errors::Unauthenticated, 'no identity resolved from request' if identity.nil?
+
+        identity
+      end
+
+      # Query string for a query, JSON body for an action; never both.
+      def arguments_for(command, name, descriptor)
+        args = if command == :query
+                 ArgumentDecoder.decode(request.query_string, input_schema: descriptor[:input_schema])
+               else
+                 parse_body!
+               end
+
+        # Unconditional: §8.1 item 5 makes coerce-then-validate a MUST.
+        RequestValidation.validate_arguments!(
+          args, input_schema: descriptor[:input_schema], verb: name, query: command == :query
+        )
+
+        args
+      end
+
+      def parse_body!
+        raw = request.raw_post
+        return {} if raw.to_s.empty?
+
+        parsed = JSON.parse(raw, symbolize_names: true)
+        raise Errors::BadRequest, 'request body must be a JSON object' unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError
+        raise Errors.malformed_json(hint: BODY_HINT)
+      end
+
+      # A {Result}. `command` is the policy verb ({Executor::VERBS}); `name` the wire 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.
+        timezone = CallerTimezone.from_env(request.env)
+        toll!(identity: identity, command: command, name: name, body: args)
+
+        CurrentRequest.with(identity: identity, timezone: timezone) do
+          Executor.new(connection: connection_for(identity), identity: identity)
+                  .call(kind: command, args: args, name: name, handler: handler)
+        end
+      end
+
+      def toll!(identity:, command:, name:, body:)
+        pow = PowGate.proofs_from_header(request.get_header('HTTP_KIOSK_POW'))
+
+        # A malformed proof is a 400, not a silent fresh 402.
+        RequestValidation.validate_proofs!(pow) if Kiosk.configuration.validate_requests && pow
+
+        PowGate.gate(
+          identity: identity, command: command, method: request.request_method,
+          verb: name, body: body, pow: pow
+        )
+      end
+
+      # A lease: the GUCs and `pay`'s three transactions need one connection per request.
+      def connection_for(_identity)
+        ::ActiveRecord::Base.lease_connection
+      end
+    end
+  end
+end

data/lib/kiosk/server/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    VERSION = '0.5.20'
+  end
+end