kiosk-server 0.5.20

data/lib/kiosk/server/auth_challenge_stores.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The challenge store, shared by every process on the database (§15.2).
+    module AuthChallengeStores
+      # The default: the `<schema>.auth_challenges` table ({SchemaDefinitions.auth_challenge_sql}).
+      class ActiveRecord
+        # Seconds between expired-row sweeps; a sweep bounds growth, not correctness.
+        DEFAULT_PRUNE_INTERVAL = 60
+
+        def initialize(prune_interval: DEFAULT_PRUNE_INTERVAL)
+          @prune_interval = prune_interval
+          @last_prune_at  = 0
+          @mutex          = Mutex.new
+        end
+
+        # Replaces any earlier challenge for the key.
+        def put(public_key_pem, nonce, exp)
+          return if public_key_pem.nil?
+
+          prune_if_due!
+          sql = <<~SQL.squish
+            INSERT INTO #{table} AS c (public_key, nonce, expires_at)
+            VALUES ($1, $2, to_timestamp($3))
+            ON CONFLICT (public_key) DO UPDATE
+              SET nonce = EXCLUDED.nonce, expires_at = EXCLUDED.expires_at
+          SQL
+          connection.exec_query(sql, 'Kiosk auth_challenge put', [public_key_pem, nonce, exp.to_i])
+          nil
+        end
+
+        # One atomic DELETE, so two processes presenting one challenge get one `true`.
+        def take(public_key_pem, nonce) # rubocop:disable Naming/PredicateMethod -- `take` is the store contract `config.auth_challenge_store` names
+          return false if public_key_pem.nil? || nonce.nil?
+
+          sql = <<~SQL.squish
+            DELETE FROM #{table}
+            WHERE public_key = $1 AND nonce = $2 AND expires_at > now()
+            RETURNING public_key
+          SQL
+          rows = connection.exec_query(
+            sql, 'Kiosk auth_challenge take', [public_key_pem, nonce]
+          ).to_a
+          !rows.empty?
+        end
+
+        def prune!
+          connection.exec_query(%(DELETE FROM #{table} WHERE expires_at <= now()),
+                                'Kiosk auth_challenge prune')
+          nil
+        end
+
+        private
+
+        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}".auth_challenges)
+      end
+    end
+  end
+end

data/lib/kiosk/server/auth_toll.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+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
+    # 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
+    # (deploy/README.md "Edge rate-limit").
+    module AuthToll
+      module_function
+
+      def on?(config = Kiosk.configuration) = config.registration_pow_count.to_i.positive?
+
+      # `verb` and `body` make the fingerprint, so a proof pays for this request only.
+      def gate(verb:, body:, pow:, config: Kiosk.configuration)
+        return unless on?(config)
+
+        secret = secret!(config)
+        spec = { alg: 'equihash', params: ::Kiosk::Pow::Equihash.params, count: config.registration_pow_count.to_i }
+        fp = PowGate.request_fingerprint(method: 'POST', verb: verb, body: body)
+
+        PowToll.new(spec: spec, fingerprint: fp, secret: secret, config: config).collect!(pow)
+        nil
+      end
+
+      def secret!(config)
+        unless defined?(::Kiosk::Reputation) && defined?(::Kiosk::Pow::Equihash)
+          raise Errors::ConfigurationError,
+                'registration_pow_count > 0 requires kiosk-reputation and kiosk-pow-equihash. ' \
+                'Add both gems (and `require` them) to your app.'
+        end
+
+        secret = config.pow_secret
+        return secret unless secret.nil? || secret.to_s.strip.empty?
+
+        raise Errors::ConfigurationError,
+              'registration_pow_count > 0 requires pow_secret. ' \
+              "Set: Kiosk.configure { |c| c.pow_secret = ENV.fetch('KIOSK_POW_SECRET') }"
+      end
+    end
+  end
+end

data/lib/kiosk/server/binding_module_gate.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Answers `501 module_not_served` on every account-binding endpoint when
+    # `c.serve_account_binding` is false. Runs before the request is read; on
+    # `/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"
+
+      private
+
+      def refuse_unserved_binding
+        return if Kiosk.configuration.serve_account_binding
+
+        error = Errors::ModuleNotServed.new(DETAIL, hint: HINT)
+        Headers.add_to(response.headers)
+        Headers.add_cache_policy(response.headers, status: error.http_status)
+        render json: error.to_problem, status: error.http_status,
+               content_type: Errors::PROBLEM_CONTENT_TYPE
+      end
+    end
+  end
+end

data/lib/kiosk/server/caller_timezone.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/time/zones'
+require 'kiosk/protocol'
+
+module Kiosk
+  module Server
+    # `Kiosk-Timezone`: the zone of the human the assistant acts for. A service
+    # time is on the clock of its place whatever this says; an operator may use it
+    # to tell the caller that the place's clock differs from theirs.
+    module CallerTimezone
+      HEADER  = Kiosk::Protocol::HEADER_TIMEZONE
+      ENV_KEY = 'HTTP_KIOSK_TIMEZONE'
+
+      # An IANA `Area/Location` name or `UTC` only: no offsets (no DST), no Rails
+      # friendly names, no legacy ids like `EST`.
+      SHAPE = %r{\A(?:UTC|[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)+)\z}
+
+      HINT = 'send an IANA zone name — Area/Location (e.g. Europe/Dublin) or the literal UTC. ' \
+             'A UTC offset (+03:00) is not accepted: it cannot carry a DST transition. ' \
+             'Take the zone from the human you are acting for, never from the machine you run on.'
+
+      module_function
+
+      # nil when the caller declared no zone; raises BadRequest on one it cannot read.
+      def from_env(env)
+        from_value(env && env[ENV_KEY])
+      end
+
+      def from_value(raw)
+        value = raw.to_s.strip
+        return nil if value.empty?
+
+        refuse(raw) unless SHAPE.match?(value)
+        zone = ::Time.find_zone(value)
+        refuse(raw) if zone.nil?
+
+        zone
+      end
+
+      # §9.1: refused by name, never silently reinterpreted.
+      def refuse(raw)
+        raise Errors::BadRequest.new(
+          "invalid #{HEADER}: #{raw.to_s.strip.inspect}",
+          hint: HINT
+        )
+      end
+    end
+  end
+end

data/lib/kiosk/server/column_spending_cap.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # A `config.spending_cap` that reads `agents.spending_cap_cents` and
+    # `agents.spending_cap_currency`: `{ amount_cents:, currency: }`, or nil (no
+    # cap, or no live assistant).
+    #
+    #   Kiosk.configure { |c| c.spending_cap = Kiosk::Server::ColumnSpendingCap.new }
+    class ColumnSpendingCap
+      def call(agent_id:)
+        return nil if agent_id.nil?
+
+        # The leased connection: the cap is read inside the transaction that charges.
+        row = ::ActiveRecord::Base.lease_connection.exec_query(<<~SQL.squish, 'Kiosk spending cap', [agent_id]).to_a.first
+          SELECT spending_cap_cents, spending_cap_currency
+          FROM "#{Kiosk.configuration.schema}".agents
+          WHERE id = $1 AND revoked_at IS NULL
+        SQL
+        return nil if row.nil? || row['spending_cap_cents'].nil?
+
+        { amount_cents: row['spending_cap_cents'].to_i, currency: row['spending_cap_currency'] }
+      end
+    end
+  end
+end

data/lib/kiosk/server/configuration_extension.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Server settings, added to {Kiosk::Configuration}.
+    module ConfigurationExtension
+      # Serialises the first touch of each lazy store slot, so racing threads
+      # cannot each build their own store (a double-spent proof of work).
+      LAZY_STORE_MUTEX = Mutex.new
+
+      # The discovery settings: where the wire is mounted and what it advertises.
+      module Discovery
+        # Default `/kiosk`. Discovery advertises `endpoint = origin + mount_path`.
+        attr_writer :mount_path
+
+        def mount_path
+          @mount_path ||= Kiosk::Protocol::DEFAULT_MOUNT_PATH
+        end
+
+        # Module names advertised in `/.well-known/kiosk.json`. Computed from what
+        # is registered and configured. An operator cannot set them.
+        def capabilities
+          computed_capabilities
+        end
+
+        # Free-form owner block for discovery, e.g. `{ name:, support: }`.
+        attr_writer :owner
+
+        def owner
+          @owner ||= {}
+        end
+
+        # The skill this origin was built against. Discovery emits the `skill`
+        # block only when `skill_sha256` is set.
+        attr_writer :skill_url
+
+        def skill_url
+          @skill_url ||= 'https://kiosk.tech/skill-v0.5.20.md'
+        end
+        attr_accessor :skill_sha256
+
+        private
+
+        # The spec's order; `events` stays last.
+        def computed_capabilities
+          has_queries = Kiosk::Server::Queries.known.any?
+          has_actions = Kiosk::Server::Actions.known.any?
+          {
+            'schema' => has_queries || has_actions,
+            'queries' => has_queries,
+            'actions' => has_actions,
+            'pay' => !payment_provider.nil?,
+            'events' => Kiosk::Server::Events.known.any?
+          }.select { |_, served| served }.keys.freeze
+        end
+      end
+
+      # The proof-of-work settings: registration proofs and the reputation challenge.
+      module ProofOfWork
+        # Equihash proofs asked at `POST /auth/register`, at the link-code claim and
+        # at the first token poll of each device code, at the gem's default params.
+        # Default 0 (open). Above 0 needs `pow_secret` and `kiosk-pow-equihash`.
+        attr_writer :registration_pow_count
+
+        def registration_pow_count
+          @registration_pow_count ||= 0
+        end
+
+        # Decides when and how hard to challenge. Default nil: never.
+        # `#challenge_for(identity:, verb:, factors:) → {alg:, params:, count:} | nil`;
+        # the verb it receives is `:run`, never `:action`.
+        def reputation_policy=(value)
+          VerbVocabulary.assert!(value, :challenge_for, 'reputation_policy #challenge_for') unless value.nil?
+          @reputation_policy = value
+        end
+
+        def reputation_policy
+          @reputation_policy
+        end
+
+        # HMAC key for proof-of-work challenges, at least 32 bytes.
+        attr_reader :pow_secret
+
+        def pow_secret=(value)
+          if value.to_s.bytesize < 32
+            raise Errors::ConfigurationError,
+                  "c.pow_secret must be at least 32 bytes (got #{value.to_s.bytesize}). " \
+                  'Generate one with `openssl rand -hex 32`.'
+          end
+
+          @pow_secret = value
+        end
+
+        # Seconds. Default 300.
+        attr_writer :pow_ttl
+
+        def pow_ttl
+          @pow_ttl ||= 300
+        end
+      end
+
+      # The anonymized-KYC attestation settings.
+      module Kyc
+        # Anonymized attributes gated actions need, e.g. %w[age_over_18].
+        attr_writer :kyc_claims
+
+        def kyc_claims
+          @kyc_claims || []
+        end
+
+        # Must match the `iss` of submitted KYC attestations.
+        attr_writer :kyc_issuer
+
+        def kyc_issuer
+          @kyc_issuer
+        end
+
+        # The `aud` a KYC attestation must carry. Default: the origin being served.
+        attr_writer :kyc_audience
+
+        def kyc_audience
+          @kyc_audience || Kiosk.current_issuer
+        end
+
+        # The KYC provider's RSA key: an OpenSSL::PKey or a PEM string.
+        def kyc_public_key
+          @kyc_public_key
+        end
+
+        def kyc_public_key=(value)
+          @kyc_public_key = case value
+                            when OpenSSL::PKey::PKey then value
+                            when String              then OpenSSL::PKey::RSA.new(value)
+                            when nil                 then nil
+                            else
+                              raise ArgumentError,
+                                    "kyc_public_key must be an OpenSSL::PKey or PEM string, got #{value.class}"
+                            end
+        end
+      end
+
+      # The database settings: where Kiosk's tables live and how a request reaches them.
+      module Database
+        # Postgres schema for Kiosk's own tables and functions. Default 'kiosk'.
+        attr_writer :schema
+
+        def schema
+          @schema ||= 'kiosk'
+        end
+
+        # Prefix of the session GUCs a request sets, e.g. `app.user_id`. Default 'app'.
+        attr_writer :guc_namespace
+
+        def guc_namespace
+          @guc_namespace ||= Kiosk::GUC::DEFAULT_NAMESPACE
+        end
+
+        # When true, every request transaction runs `SET LOCAL ROLE <app_role>`;
+        # that role then needs grants on every table the verbs touch. Default false.
+        attr_writer :enforce_db_role
+
+        def enforce_db_role
+          @enforce_db_role ||= false
+        end
+      end
+
+      include Discovery
+      include ProofOfWork
+      include Kyc
+      include Database
+
+      # Required. A SigningKey or a PEM string.
+      def signing_key
+        @signing_key || raise(Errors::ConfigurationError,
+                              'c.signing_key is not set. Generate one with `openssl genrsa 2048`.')
+      end
+
+      def signing_key=(value)
+        @signing_key = case value
+                       when Kiosk::Server::SigningKey, nil then value
+                       when String then Kiosk::Server::SigningKey.from_pem(value)
+                       else raise ArgumentError, "signing_key must be a SigningKey or PEM string, got #{value.class}"
+                       end
+      end
+
+      # The role every self-registered agent is pinned to, and the default a
+      # binding falls back to. Required, and one of {#roles}, when {#roles} is set.
+      #   Kiosk.configure { |c| c.roles = %i[customer]; c.registration_role = :customer }
+      attr_accessor :registration_role
+
+      # Optional `->(public_key) { record_id }` creating the account behind a
+      # self-registered agent. Unset: `user_model.constantize.create!`.
+      attr_accessor :assistant_creation
+
+      # Account-binding ceremony state. Default: the shared database store.
+      attr_writer :device_authorization_store
+
+      def device_authorization_store
+        @device_authorization_store ||
+          LAZY_STORE_MUTEX.synchronize do
+            @device_authorization_store ||=
+              Kiosk::Server::DeviceAuthorizationStores::ActiveRecord.new
+          end
+      end
+
+      # Per-identity event tail. Default: the shared database table.
+      attr_writer :event_store
+
+      def event_store
+        @event_store ||
+          LAZY_STORE_MUTEX.synchronize { @event_store ||= Kiosk::Server::EventStores::ActiveRecord.new }
+      end
+
+      # Optional sign-in path a browser is redirected to from the assistants and
+      # verify pages. Unset, or for an API request: a plain 401.
+      attr_accessor :sign_in_path
+
+      # Default true. False answers every binding path `501 module_not_served`.
+      attr_writer :serve_account_binding
+
+      def serve_account_binding
+        return @serve_account_binding unless @serve_account_binding.nil?
+
+        true
+      end
+
+      # Called as `(agent:, from:, to:)` when an assistant's key moves from one
+      # account to another, inside the rebind transaction: the place to move
+      # the operator's own rows. `from` and `to` are `user_model` records.
+      attr_accessor :assistant_claimed
+
+      # Called as `(agent:, account:)` after an assistant is unlinked from
+      # `account`, a `user_model` record, and its tokens are revoked.
+      attr_accessor :assistant_unlinked
+
+      # Optional `(agent_id:) → { amount_cents:, currency: } | nil`, checked
+      # before capture; 0 blocks payments, and so does a cart in another currency.
+      # {Kiosk::Server::ColumnSpendingCap} reads
+      # `agents.spending_cap_cents`, the column edited by the manage-assistants
+      # page, and `agents.spending_cap_currency`.
+      attr_accessor :spending_cap
+
+      # Days of settled spend summed against the cap. Default nil: all time.
+      attr_accessor :spending_cap_window_days
+
+      # `call(id, lines) → cents | String`: the payable row's price, or why the cart is refused.
+      attr_accessor :cart_price_checker
+
+      # Optional `call(id)`, run once the settlement that paid row `id` is recorded.
+      attr_accessor :after_payment
+
+      # Default true. Malformed `Kiosk-PoW` and reserved-endpoint bodies are a 400
+      # naming the problem, rather than an endless re-challenge.
+      attr_writer :validate_requests
+
+      def validate_requests
+        return @validate_requests unless @validate_requests.nil?
+
+        true
+      end
+
+      # Default false. Checks each answer against its verb's `output_schema`
+      # and raises on mismatch: an operator-side bug, so for development and CI.
+      attr_writer :validate_responses
+
+      def validate_responses
+        @validate_responses ||= false
+      end
+
+      # Optional callable receiving one {Kiosk::Server::ActionEvent} per action
+      # invocation, arguments unredacted. Default nil: nothing is emitted.
+      # A sink that raises does not fail the action.
+      attr_reader :audit_sink
+
+      def audit_sink=(value)
+        if !value.nil? && !value.respond_to?(:call)
+          raise ArgumentError,
+                'audit_sink must be callable (a lambda or any object answering #call) ' \
+                "or nil to emit nothing, got #{value.class}"
+        end
+
+        @audit_sink = value
+      end
+
+      # Spent challenge ids, so a proof is accepted once. Default: the shared database table.
+      attr_writer :pow_spent_store
+
+      def pow_spent_store
+        @pow_spent_store ||
+          LAZY_STORE_MUTEX.synchronize { @pow_spent_store ||= Kiosk::Server::PowSpentStores::ActiveRecord.new }
+      end
+
+      # Outstanding auth nonces. Default: the shared database table.
+      attr_writer :auth_challenge_store
+
+      def auth_challenge_store
+        @auth_challenge_store ||
+          LAZY_STORE_MUTEX.synchronize do
+            @auth_challenge_store ||= Kiosk::Server::AuthChallengeStores::ActiveRecord.new
+          end
+      end
+
+      # Seconds an access token lives. One paid proof-of-work toll lasts as long. Default 3600.
+      attr_writer :access_token_ttl
+
+      def access_token_ttl
+        @access_token_ttl ||= JwtIssuer::DEFAULT_EXPIRES_IN
+      end
+
+      # Seconds between `GET /auth/challenge` and the signed POST. Default covers
+      # the auth toll's proof-of-work window plus 60s.
+      attr_writer :auth_challenge_ttl
+
+      def auth_challenge_ttl
+        @auth_challenge_ttl ||= (pow_ttl * [registration_pow_count.to_i, 1].max) + 60
+      end
+
+      # Revocation watermarks, checked on every access token. Default: the
+      # shared database table, so a revoke or an unlink holds in every process.
+      attr_writer :revocation_store
+
+      def revocation_store
+        @revocation_store ||
+          LAZY_STORE_MUTEX.synchronize { @revocation_store ||= Kiosk::Server::RevocationStores::ActiveRecord.new }
+      end
+    end
+  end
+end

data/lib/kiosk/server/controller_verb.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The registry entry of a verb that a controller action answers. A named
+    # controller is held by name and resolved per request, so a development
+    # reload serves the edited class.
+    class ControllerVerb
+      attr_reader :method_name, :wire_name, :kind
+
+      def initialize(controller:, method_name:, wire_name:, kind:)
+        @controller  = controller.is_a?(Class) && controller.name ? controller.name : controller
+        @method_name = method_name.to_s
+        @wire_name   = wire_name.to_s
+        @kind        = kind
+      end
+
+      # nil for an anonymous controller class.
+      def controller_name = @controller.is_a?(String) ? @controller : @controller.name
+
+      # The controller class whose action answers the verb, or nil when none can.
+      def controller
+        resolve!
+      rescue Errors::VerbNotFound
+        nil
+      end
+
+      # {VerbController} reaches this only when {#controller} is nil; it raises why no action answers.
+      def call(_args)
+        controller = resolve!
+        raise ArgumentError, "#{controller}##{@method_name} answers #{@wire_name.inspect} through its own route"
+      end
+
+      # Handy in `p`/logs and in the specs that assert what got registered.
+      def inspect
+        "#<#{self.class.name} #{@kind} #{@wire_name.inspect} → " \
+          "#{controller_name || @controller}##{@method_name}>"
+      end
+
+      private
+
+      def resolve!
+        controller = @controller.is_a?(String) ? constantize! : @controller
+        return controller if controller.action_methods.include?(@method_name)
+
+        raise Errors::VerbNotFound.new(
+          "#{@kind} #{@wire_name.inspect} is no longer dispatchable",
+          hint: "#{controller_name || controller}##{@method_name} is not a public controller action"
+        )
+      end
+
+      def constantize!
+        @controller.constantize
+      rescue NameError
+        # `verb_not_found`: nothing was addressed, and the caller should stop calling this name.
+        raise Errors::VerbNotFound.new(
+          "#{@kind} #{@wire_name.inspect} is registered to #{@controller}, which is not loaded",
+          hint: 'the handler class was renamed or removed; restart the server after moving it'
+        )
+      end
+    end
+  end
+end

data/lib/kiosk/server/current_request.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The wire request being dispatched, visible to its handler for the duration
+    # of one block. Fiber-local: a handler that hands work to another thread must
+    # pass what it needs.
+    module CurrentRequest
+      KEY   = :kiosk_server_current_request
+      EMPTY = {}.freeze
+
+      module_function
+
+      # An inner `with` blanks what it omits.
+      def with(identity: nil, timezone: nil)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = { identity: identity, timezone: timezone }
+        yield
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      def identity = current[:identity]
+
+      # The caller's {CallerTimezone}, or nil when it declared none.
+      def timezone = current[:timezone]
+
+      def current = Thread.current[KEY] || EMPTY
+    end
+  end
+end

data/lib/kiosk/server/cursor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # An offset cursor, published as a decimal integer in clear: a cursor
+    # authorises nothing, and opacity is the client's contract, not the token's.
+    # A present cursor that is not one this helper wrote is a 400.
+    module Cursor
+      OFFSET_RE = /\A[0-9]+\z/
+
+      module_function
+
+      def encode_offset(offset)
+        offset.to_i.to_s
+      end
+
+      def decode_offset(cursor, default: 0)
+        return default if cursor.nil? || cursor.to_s.empty?
+
+        raw = cursor.to_s
+        unless raw.match?(OFFSET_RE)
+          raise Errors::BadRequest.new(
+            "cursor #{raw.inspect} is not a cursor this endpoint issued",
+            hint: 'do not build a cursor: fetch the `Link: <…>; rel="next"` target verbatim, ' \
+                  'or copy its `cursor` parameter byte for byte. Omit `cursor` for the first page.'
+          )
+        end
+
+        Integer(raw, 10)
+      end
+    end
+  end
+end