kiosk-server 0.5.20

data/lib/kiosk/server/action_event.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # One action invocation, as `Kiosk.configuration.audit_sink` receives it.
+    # {#args} arrive unredacted: whoever stores this event controls that data.
+    # {#cause_class}/{#cause_message} carry the handler's own error under a Kiosk wrapper.
+    class ActionEvent < Data.define(:action, :user_id, :agent_id, :role, :actor, :args,
+                                    :status, :error_class, :error_message,
+                                    :cause_class, :cause_message, :invoked_at)
+      OK    = 'ok'
+      ERROR = 'error'
+
+      def self.build(identity:, name:, args:, status:, error: nil, invoked_at: Time.current) # rubocop:disable Metrics/ParameterLists -- the public keyword API that the executor and audit sinks call
+        new(action: name.to_s, **principal(identity), args: args.is_a?(Hash) ? args : {},
+            status: status.to_s, **failure(error), invoked_at: invoked_at)
+      end
+
+      def self.principal(identity)
+        { user_id: identity.user_id, agent_id: identity.agent_id, role: identity.role, actor: identity.actor }
+      end
+
+      # The error and its cause as class names and messages; all nil without an error.
+      def self.failure(error)
+        cause = cause_of(error)
+        { error_class: error&.class&.name, error_message: error && error.message.to_s,
+          cause_class: cause&.class&.name, cause_message: cause && cause.message.to_s }
+      end
+
+      # An exception re-raised inside its own `rescue` can be its own cause.
+      def self.cause_of(error)
+        return nil unless error.is_a?(::Exception)
+
+        cause = error.cause
+        cause.is_a?(::Exception) && !cause.equal?(error) ? cause : nil
+      end
+
+      # `{"salon_id" => "integer", "slot" => "string"}`, in JSON Schema type names.
+      def arg_types
+        args.to_h { |key, value| [key.to_s, self.class.json_type(value)] }
+      end
+
+      def with_arg_types = with(args: arg_types)
+
+      def without_args = with(args: {})
+
+      def self.json_type(value)
+        case value
+        when nil            then 'null'
+        when true, false    then 'boolean'
+        when Integer        then 'integer'
+        when Float, Numeric then 'number'
+        when Array          then 'array'
+        when Hash           then 'object'
+        else 'string'
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/actions.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Registry of actions (`kind :action`): verbs that change something the
+    # operator owns. The behaviour is {VerbRegistry}.
+    module Actions
+      SCOPE = :action
+      Entry = VerbRegistry::Entry
+
+      extend VerbRegistry
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+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.
+      class DefaultAgentIdp < Kiosk::AgentIdentityProviders::Base
+        def verify(request)
+          header = authorization_for(request)
+          return nil if header.blank?
+
+          claims = verified_claims(header.sub(/\ABearer\s+/i, ''))
+          Kiosk::Identity.new(
+            user_id: claims[:sub], role: claims[:role], actor: 'agent',
+            agent_id: claims[:agent_id], claims: claims
+          )
+        rescue JwtIssuer::Error
+          nil
+        end
+
+        def issue(agent_id:, role:)
+          claims = { sub: lookup_user_id(agent_id), agent_id: agent_id, actor: 'agent' }
+          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),
+            expires_in: Kiosk.configuration.access_token_ttl
+          )
+        end
+
+        def agent_payment_key(agent_id)
+          pem = agents_column('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)
+        end
+
+        private
+
+        def verified_claims(token)
+          JwtIssuer.verify(
+            token: token,
+            jwks: Jwks.build(keys: [Kiosk.configuration.signing_key]),
+            audience: Kiosk.current_issuer,
+            issuer: Kiosk.current_issuer
+          )
+        end
+
+        # Never earlier than the revocation watermark, so a token minted in the
+        # second a rebind revoked (§6.3) still survives `iat < watermark`.
+        def mint_instant(agent_id)
+          now       = Time.current
+          watermark = Kiosk.configuration.revocation_store.watermark_for(agent_id)
+          return now if watermark.nil? || watermark <= now.to_i
+
+          Time.at(watermark).utc
+        end
+
+        def lookup_user_id(agent_id)
+          row = agents_column('user_id', agent_id)
+          raise Kiosk::AgentIdentityProviders::InvalidToken, "unknown agent #{agent_id}" if row.nil?
+
+          row.fetch('user_id')
+        end
+
+        # `column` is always a literal from this class, never caller input.
+        def agents_column(column, agent_id)
+          ::ActiveRecord::Base.lease_connection.exec_query(
+            "SELECT #{column} FROM #{schema}.agents WHERE id = $1 AND revoked_at IS NULL",
+            "Kiosk agent #{column}",
+            [agent_id]
+          ).to_a.first
+        end
+
+        def schema = Kiosk.configuration.schema
+
+        def authorization_for(request)
+          if request.respond_to?(:headers)
+            request.headers['Authorization'] || request.headers['authorization']
+          elsif request.is_a?(Hash)
+            request['HTTP_AUTHORIZATION']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/agent_login.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Login with an already-registered public key: proves possession and mints a
+    # fresh token. An unknown key is a 404, never a new account.
+    module AgentLogin
+      module_function
+
+      def call(public_key_pem:, signed:)
+        pem = public_key_pem.to_s.strip
+
+        # Prove possession BEFORE any lookup or state change.
+        payload = PopVerifier.verify!(public_key_pem: pem, signed: signed)
+        AuthChallenge.consume!(public_key_pem: pem, nonce: payload.fetch(:nonce))
+
+        row      = registered_agent(pem)
+        agent_id = row.fetch('id')
+        role     = primary_role(row.fetch('allowed_roles'))
+        token    = AgentIdentityProviders::DefaultAgentIdp.new.issue(agent_id: agent_id, role: role)
+        { access_token: token }
+      end
+
+      def registered_agent(pem)
+        row = ::ActiveRecord::Base.lease_connection.exec_query(<<~SQL.squish, 'Kiosk agent lookup by key', [pem, Kiosk.current_issuer]).to_a.first
+          SELECT id, user_id, allowed_roles FROM #{Kiosk.configuration.schema}.agents
+          WHERE public_key = $1 AND issuer = $2 AND revoked_at IS NULL
+          LIMIT 1
+        SQL
+        return row if row
+
+        raise Errors::NotFound.new(
+          'no agent registered for this public key',
+          hint: 'POST /auth/register to create an identity for a new key'
+        )
+      end
+      private_class_method :registered_agent
+
+      # `allowed_roles` is an Array or a text[] literal ("{customer}"), by adapter.
+      def primary_role(allowed_roles)
+        case allowed_roles
+        when Array then allowed_roles.first
+        else allowed_roles.to_s.delete('{}').split(',').first
+        end
+      end
+      private_class_method :primary_role
+    end
+  end
+end

data/lib/kiosk/server/agent_registration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support/core_ext/string/inflections' # String#constantize
+
+module Kiosk
+  module Server
+    # Self-registration with no human: creates the assistant account, binds an
+    # agent to the key, and mints its first token.
+    module AgentRegistration
+      module_function
+
+      def call(public_key_pem:, signed:, pow: nil)
+        config = Kiosk.configuration
+        role   = registration_role(config)
+        public_key_pem = public_key_pem.to_s.strip
+
+        AuthToll.gate(verb: 'auth/register', body: { public_key: public_key_pem }, pow: pow, config: config)
+
+        # Prove possession of the private key before any lookup or write.
+        payload = PopVerifier.verify!(public_key_pem: public_key_pem, signed: signed)
+        AuthChallenge.consume!(public_key_pem: public_key_pem, nonce: payload.fetch(:nonce))
+
+        conn = ::ActiveRecord::Base.lease_connection
+        refuse_known_key!(conn, config, public_key_pem)
+        conn.transaction { register(conn, config, public_key_pem, role) }
+      end
+
+      # The operator's `assistant_creation` factory, else a bare `user_model.create!`.
+      def create_assistant_account(config, public_key_pem)
+        return config.user_model.constantize.create!.id unless config.assistant_creation
+
+        id = config.assistant_creation.call(public_key_pem)
+        return id unless id.nil?
+
+        raise Errors::ConfigurationError,
+              'config.assistant_creation returned nil. The block must create the ' \
+              'assistant account and RETURN its id (used as agents.user_id), e.g. ' \
+              'c.assistant_creation = ->(pubkey) { AssistantAccount.create!(...).id }'
+      end
+
+      # The role is the server's choice, never the agent's.
+      def registration_role(config)
+        role = config.registration_role&.to_s
+        return if role.blank?
+        return role if config.roles.map(&:to_s).include?(role)
+
+        raise Errors::ConfigurationError,
+              "registration_role #{role.inspect} is not among configured roles " \
+              "#{config.roles.inspect}"
+      end
+
+      # A known key logs in instead; it is never registered twice.
+      def refuse_known_key!(conn, config, public_key_pem)
+        existing = conn.exec_query(<<~SQL.squish, 'Kiosk agent lookup by key', [public_key_pem, Kiosk.current_issuer]).to_a.first
+          SELECT id FROM #{config.schema}.agents
+          WHERE public_key = $1 AND issuer = $2 AND revoked_at IS NULL
+          LIMIT 1
+        SQL
+        return unless existing
+
+        raise Errors::Conflict.new(
+          'public key already registered',
+          hint: 'use POST /auth/login to refresh a token for an existing key'
+        )
+      end
+
+      def register(conn, config, public_key_pem, role)
+        assistant_account_id = create_assistant_account(config, public_key_pem)
+        agent_id = insert_agent(conn, config, [assistant_account_id, public_key_pem, Kiosk.current_issuer], role)
+        token = AgentIdentityProviders::DefaultAgentIdp.new.issue(agent_id: agent_id, role: role)
+        { agent_id: agent_id, user_id: assistant_account_id.to_s, access_token: token }
+      end
+
+      # No role is the empty array: `allowed_roles` is NOT NULL.
+      def insert_agent(conn, config, binds, role)
+        allowed_roles_sql, role_binds = role ? ['ARRAY[$4]::text[]', [role]] : ["'{}'::text[]", []]
+        rows = conn.exec_query(<<~SQL.squish, 'Kiosk agent insert', [*binds, *role_binds])
+          INSERT INTO #{config.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
+      private_class_method :registration_role, :refuse_known_key!, :register, :insert_agent
+    end
+  end
+end

data/lib/kiosk/server/argument_decoder.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+require 'rack'
+
+module Kiosk
+  module Server
+    # Decodes a query's arguments from the URL query string and coerces them
+    # to the types `input_schema` declares. Validation runs afterwards, on the
+    # coerced result (RequestValidation).
+    module ArgumentDecoder
+      module_function
+
+      # Reserved names and their types. A verb never declares `cursor`; it may declare `limit` (§8.1 item 6).
+      RESERVED = { 'limit' => 'integer', 'cursor' => 'string' }.freeze
+
+      # @param input_schema [Hash, nil] the verb's `input_schema`, symbol- or string-keyed
+      # @raise [Errors::BadRequest] naming the parameter
+      def decode(query_string, input_schema: nil)
+        raw = QueryShape.parse!(query_string)
+        raw = QueryShape.fold_declared_arrays(raw, query_string, input_schema)
+        QueryShape.reject_undecodable_shapes!(raw)
+        coerce_all(raw, input_schema)
+      end
+
+      def coerce_all(raw, input_schema)
+        raw.each_with_object({}) do |(name, value), out|
+          out[name.to_sym] = Coercion.coerce(value, property_for(name, input_schema), name.to_s)
+        end
+      end
+
+      # An undeclared parameter stays a String; whether it is allowed is the validator's call.
+      def property_for(name, input_schema)
+        declared = fetch(fetch(input_schema, :properties), name)
+        return declared unless declared.nil?
+
+        reserved = RESERVED[name.to_s]
+        reserved && { 'type' => reserved }
+      end
+
+      def fetch(hash, key)
+        return nil unless hash.is_a?(::Hash)
+        return hash[key.to_sym] if hash.key?(key.to_sym)
+
+        hash[key.to_s]
+      end
+
+      # A nullable union like `["integer", "null"]` coerces to its non-null member.
+      def declared_type(property)
+        type = fetch(property, :type)
+        case type
+        when ::Array then type.map(&:to_s).reject { |t| t == 'null' }.first
+        when nil     then nil
+        else type.to_s
+        end
+      end
+
+      # What a caller has to send for each string `format` the wire reads.
+      FORMAT_SPELLINGS = {
+        'date' => 'a calendar date as YYYY-MM-DD, e.g. 2026-08-19',
+        'date-time' => 'an ISO 8601 timestamp, e.g. 2026-08-19T14:00:00Z'
+      }.freeze
+
+      SHAPE_HINT =
+        'query arguments are scalars (`a=v`), arrays of scalars (repeated ' \
+        '`a%5B%5D=v`) or one level of object with scalar leaves ' \
+        '(`o%5Bk%5D=v`); a name is one shape or the other, never both.'
+
+      DEPTH_HINT =
+        "a query's arguments are one level deep. A read whose input needs an " \
+        'array of objects or two levels of nesting is an ACTION — POST it to ' \
+        '<endpoint>/<action-name> with a JSON body.'
+
+      NARROWING_HINT =
+        "an object argument's leaves are SCALARS: `o%5Bk%5D=v`, not " \
+        '`o%5Bk%5D%5B%5D=v`. Anything richer is an ACTION (POST).'
+
+      # The query string's shape: what Rack can decode and the wire accepts.
+      module QueryShape
+        module_function
+
+        def parse!(query_string)
+          Rack::Utils.parse_nested_query(query_string.to_s)
+        rescue ::Rack::BadRequest
+          raise Errors::BadRequest.new(
+            'the query string could not be decoded',
+            hint: SHAPE_HINT
+          )
+        end
+
+        # A bare repeated `a=1&a=2` becomes an array only when the verb declares
+        # `type: "array"`; otherwise Rack's last value wins.
+        def fold_declared_arrays(raw, query_string, input_schema)
+          flat = nil
+          raw.each_with_object({}) do |(name, value), out|
+            unless value.is_a?(::String) && declared_array?(name, input_schema)
+              out[name] = value
+              next
+            end
+
+            flat ||= ::Rack::Utils.parse_query(query_string.to_s)
+            repeated = flat[name]
+            out[name] = repeated.nil? ? [value] : Array(repeated)
+          end
+        end
+
+        def declared_array?(name, input_schema)
+          ArgumentDecoder.declared_type(ArgumentDecoder.property_for(name, input_schema)) == 'array'
+        end
+
+        def reject_undecodable_shapes!(raw)
+          raw.each do |name, value|
+            case value
+            when ::Array then reject_nonscalar_elements!(name, value)
+            when ::Hash  then reject_nonscalar_leaves!(name, value)
+            end
+          end
+          raw
+        end
+
+        def reject_nonscalar_elements!(name, value)
+          value.each do |element|
+            next if element.nil? || element.is_a?(::String)
+
+            raise Errors::BadRequest.new(
+              "parameter #{name.inspect} is an array of " \
+              "#{element.is_a?(::Hash) ? 'objects' : 'arrays'}, which a query cannot carry",
+              hint: DEPTH_HINT
+            )
+          end
+        end
+
+        # An array leaf is the scalar-leaves rule; a hash leaf is the depth limit.
+        def reject_nonscalar_leaves!(name, value)
+          value.each do |key, leaf|
+            next if leaf.nil? || leaf.is_a?(::String)
+
+            raise nonscalar_leaf(name, key, leaf)
+          end
+        end
+
+        def nonscalar_leaf(name, key, leaf)
+          if leaf.is_a?(::Array)
+            return Errors::BadRequest.new(
+              "parameter #{name.inspect} has an array-valued leaf at #{name}[#{key}]",
+              hint: NARROWING_HINT
+            )
+          end
+
+          Errors::BadRequest.new(
+            "parameter #{name.inspect} nests two levels deep at #{name}[#{key}]",
+            hint: DEPTH_HINT
+          )
+        end
+      end
+
+      # Coerces one decoded value to the type its property declares.
+      module Coercion
+        module_function
+
+        SCALARS = { 'integer' => :to_integer, 'number' => :to_number, 'boolean' => :to_boolean }.freeze
+
+        def coerce(value, property, path)
+          return value if value.nil?
+
+          type = ArgumentDecoder.declared_type(property)
+          return public_send(SCALARS.fetch(type), value, path) if SCALARS.key?(type)
+
+          case type
+          when 'string' then to_string(value, property, path)
+          when 'array'  then to_array(value, property, path)
+          when 'object' then to_object(value, property, path)
+          else value
+          end
+        end
+
+        def to_integer(value, path)
+          scalar!(value, 'an integer', path)
+          Integer(value, 10)
+        rescue ::ArgumentError, ::TypeError
+          refuse(path, value, 'an integer', 'a JSON integer literal, e.g. 4')
+        end
+
+        def to_number(value, path)
+          scalar!(value, 'a number', path)
+          Float(value)
+        rescue ::ArgumentError, ::TypeError
+          refuse(path, value, 'a number', 'a JSON number literal, e.g. 4 or 4.5')
+        end
+
+        # Only the literals `true` and `false`.
+        def to_boolean(value, path)
+          scalar!(value, 'a boolean', path)
+          return true  if value == 'true'
+          return false if value == 'false'
+
+          refuse(path, value, 'a boolean', 'the literal true or false')
+        end
+
+        # A string stays a String; a declared `format` is checked here.
+        def to_string(value, property, path)
+          scalar!(value, 'a string', path)
+          case ArgumentDecoder.fetch(property, :format).to_s
+          when 'date'      then check_date!(value, path)
+          when 'date-time' then check_date_time!(value, path)
+          end
+          value
+        end
+
+        def check_date!(value, path)
+          parsed = begin
+            ::Date.strptime(value, '%Y-%m-%d')
+          rescue ::ArgumentError, ::TypeError
+            nil
+          end
+          return if parsed && parsed.strftime('%Y-%m-%d') == value
+
+          refuse(path, value, 'a date', FORMAT_SPELLINGS['date'])
+        end
+
+        def check_date_time!(value, path)
+          ::Time.iso8601(value)
+        rescue ::ArgumentError, ::TypeError
+          refuse(path, value, 'a timestamp', FORMAT_SPELLINGS['date-time'])
+        end
+
+        def to_array(value, property, path)
+          refuse(path, value, 'an array', "repeated #{path}%5B%5D=… parameters") if value.is_a?(::Hash)
+
+          items = ArgumentDecoder.fetch(property, :items)
+          Array(value).each_with_index.map { |element, i| coerce(element, items, "#{path}[#{i}]") }
+        end
+
+        def to_object(value, property, path)
+          refuse(path, value, 'an object', "one #{path}%5Bkey%5D=… parameter per key") unless value.is_a?(::Hash)
+
+          properties = ArgumentDecoder.fetch(property, :properties)
+          value.each_with_object({}) do |(key, leaf), out|
+            out[key.to_sym] = coerce(leaf, ArgumentDecoder.fetch(properties, key), "#{path}[#{key}]")
+          end
+        end
+
+        def scalar!(value, expected, path)
+          return unless value.is_a?(::Array) || value.is_a?(::Hash)
+
+          refuse(path, value, expected, "a single #{path}=… parameter")
+        end
+
+        def refuse(path, value, expected, spelling)
+          raise Errors::BadRequest.new(
+            "parameter #{path.inspect} is not #{expected}: #{value.inspect}",
+            hint: "#{path} is declared #{expected} — send #{spelling}. " \
+                  "GET <endpoint>/schema publishes this verb's input_schema."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/audit_sink.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Hands one {ActionEvent} per action invocation, success or failure, to the
+    # operator's `c.audit_sink` callable; with no sink nothing is built or stored.
+    # Queries, `pay` and refusals before an action ran are not emitted.
+    #
+    #   Kiosk.configure do |c|
+    #     c.audit_sink = ->(event) { AuditLog.create!(**event.to_h) }
+    #   end
+    #
+    # Called after the action's transaction has closed; a sink that raises is
+    # logged and never fails the action.
+    module AuditSink
+      class << self
+        def configured? = !Kiosk.configuration.audit_sink.nil?
+
+        def emit(event, sink: Kiosk.configuration.audit_sink)
+          return false if sink.nil?
+
+          sink.call(event)
+          true
+        rescue StandardError => e
+          report(event, e)
+          false
+        end
+
+        private
+
+        def report(event, error)
+          message = '[kiosk-server] audit_sink raised for action ' \
+                    "#{event.action.inspect}: #{error.class}: #{error.message}"
+          logger = defined?(::Rails) && ::Rails.respond_to?(:logger) ? ::Rails.logger : nil
+          logger ? logger.error(message) : warn(message)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/auth_challenge.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Kiosk
+  module Server
+    # Server side of the proof-of-possession challenge: a single-use, short-lived
+    # nonce per public key.
+    module AuthChallenge
+      module_function
+
+      # The agent signs `challenge` into its JWS; `exp` is the Unix expiry.
+      def issue(public_key_pem:, now: Time.current)
+        config = Kiosk.configuration
+        nonce  = SecureRandom.urlsafe_base64(32)
+        exp    = now.to_i + config.auth_challenge_ttl
+        config.auth_challenge_store.put(public_key_pem.to_s.strip, nonce, exp)
+        { challenge: nonce, exp: exp }
+      end
+
+      def consume!(public_key_pem:, nonce:)
+        ok = Kiosk.configuration.auth_challenge_store.take(public_key_pem.to_s.strip, nonce.to_s)
+        return true if ok
+
+        raise Errors::Unauthenticated.new(
+          'no matching auth challenge',
+          hint: 'GET /auth/challenge?public_key=… first, then sign the returned nonce; ' \
+                'challenges are single-use and short-lived'
+        )
+      end
+    end
+  end
+end