kiosk-server 0.5.20

data/lib/kiosk/server/engine.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+# The Rails engine. `kiosk` in config/routes.rb mounts it at the configured mount_path,
+# drawing the protocol plane under the mount and the discovery documents at the root.
+# `rails` first: rails/engine needs its core_ext.
+require 'rails'
+require 'rails/engine'
+
+module Kiosk
+  module Server
+    class Engine < ::Rails::Engine
+      isolate_namespace Kiosk::Server
+
+      # True when this engine is mounted anywhere in +route_set+.
+      def self.mounted_in?(route_set)
+        route_set.routes.any? do |route|
+          app = route.app
+          app.respond_to?(:app) && (app.app == self || app.app.is_a?(self))
+        end
+      end
+
+      # Outside ShowExceptions, so routing 404s and unhandled 500s carry the
+      # version headers too (§3.6); below HostAuthorization/SSL, which answer
+      # before the application is reached.
+      initializer 'kiosk-server.middleware' do |app|
+        app.middleware.insert_before ::ActionDispatch::ShowExceptions,
+                                     Kiosk::Server::HeadersMiddleware
+        app.middleware.insert_before ::ActionDispatch::ShowExceptions,
+                                     Kiosk::Server::IssuerMiddleware
+      end
+
+      # Credential-bearing wire fields, kept out of the `Parameters:` log line.
+      # Whole-key matches, so an operator's own `promo_code` is left alone.
+      FILTERED_PARAMETERS = %w[
+        signed code device_code kyc_jws
+        intent_mandate_jws cart_mandate_jws payment_mandate_jws
+      ].map { |field| /\A#{field}\z/ }.freeze
+
+      initializer 'kiosk-server.filter_parameters' do |app|
+        app.config.filter_parameters += FILTERED_PARAMETERS
+      end
+
+      # Rebuilds the registries at boot and after every development reload.
+      config.to_prepare do
+        Kiosk::Server::SchemaSlots.reset!
+        Kiosk::Server::HandlerRegistrations.reload!
+        Kiosk::Server::SchemaDocument.reset!
+        Kiosk::Server::OpenApi.reset!
+      end
+
+      # Derives the `schema` catalog after eager loading, in every environment.
+      config.after_initialize do
+        Kiosk::Server::SchemaDocument.derive!
+      end
+
+      config.after_initialize do
+        next unless Kiosk::Server::Actions.known.empty? && Kiosk::Server::Queries.known.empty?
+
+        message = '[kiosk-server] no queries or actions are registered. Put handler controllers ' \
+                  "(classes including Kiosk::Handler) in #{Kiosk::Server::HandlerRegistrations::HANDLERS_DIR}."
+        ::Rails.logger ? ::Rails.logger.warn(message) : warn(message)
+      end
+
+      # A wrong `issuer` refuses every proof with "proof audience mismatch".
+      # Warned, not raised: an operator seeds before the public origin exists.
+      LOOPBACK_ISSUER =
+        %r{\A(?:https?://)?(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[::1\])(?::\d+)?/?\z}i
+
+      # The boot-time configuration checks. Each answers a message, or nil when the configuration is sound.
+      module BootChecks
+        ISSUER_UNSET =
+          '[kiosk-server] `c.issuer` is not set, so every authenticated request is refused ' \
+          'with "proof audience mismatch". Set it to the origin assistants dial: ' \
+          'Kiosk.configure { |c| c.issuer = "https://api.example.com" }.'
+
+        ISSUER_LOOPBACK =
+          '[kiosk-server] The served origin %<origin>s is a loopback origin; no assistant can ' \
+          'reach it outside development and test. Set `c.issuer` and `c.additional_origins` ' \
+          'to public origins.'
+
+        DEFAULT_ROLE =
+          'An assistant admitted without a role would get a token with no role claim. ' \
+          'Set the least-privileged declared role as the default ' \
+          '(Kiosk.configure { |c| c.registration_role = :%<first>s }), or declare no roles (`c.roles = []`).'
+
+        def issuer_warning(config:, local:)
+          issuer = config.issuer.to_s.strip
+          return ISSUER_UNSET if issuer.empty?
+          return nil if local
+
+          loopback = [issuer, *config.additional_origins].map { |o| o.to_s.strip }
+                                                         .find { |o| LOOPBACK_ISSUER.match?(o) }
+          format(ISSUER_LOOPBACK, origin: loopback.inspect) if loopback
+        end
+
+        # An origin that declares roles must configure a `registration_role` among
+        # them; an origin with no roles needs none.
+        def default_role_configuration_error(config:)
+          declared = Array(config.roles).map(&:to_s).reject(&:empty?)
+          return nil if declared.empty?
+
+          configured = config.registration_role.to_s.strip
+          return nil if declared.include?(configured)
+
+          "#{default_role_head(config, declared, configured)} #{format(DEFAULT_ROLE, first: declared.first)}"
+        end
+
+        private
+
+        def default_role_head(config, declared, configured)
+          roles = declared.join(', ')
+          return "[kiosk-server] this origin declares roles (#{roles}) and configures no `registration_role`." if configured.empty?
+
+          "[kiosk-server] this origin declares roles (#{roles}) and its " \
+            "`registration_role` is #{config.registration_role.inspect}, which is not one of them."
+        end
+      end
+      extend BootChecks
+
+      config.after_initialize do
+        message = Kiosk::Server::Engine.issuer_warning(
+          config: Kiosk.configuration, local: ::Rails.env.local?
+        )
+        next unless message
+
+        ::Rails.logger ? ::Rails.logger.warn(message) : warn(message)
+      end
+
+      config.after_initialize do
+        message = Kiosk::Server::Engine.default_role_configuration_error(config: Kiosk.configuration)
+        raise Kiosk::Server::Errors::ConfigurationError, message if message
+      end
+
+      # A production origin that serves events needs a shared cable adapter; this raises without one.
+      config.after_initialize do
+        Kiosk::Server::EventsCable.cable_config if ::Rails.env.production? && Kiosk::Server::Events.known.any?
+      end
+
+      # `routes.append` runs after config/routes.rb is drawn, so the mount is visible here.
+      initializer 'kiosk-server.root_discovery_routes' do |app|
+        app.routes.append do
+          next unless Kiosk::Server::Engine.mounted_in?(app.routes)
+
+          get '/agents.txt',  to: 'kiosk/server/discovery#agents_txt'
+          get '/agents.json', to: 'kiosk/server/discovery#agents_json'
+          get '/auth.md',     to: 'kiosk/server/discovery#auth_md'
+          get '/.well-known/agent-configuration', to: 'kiosk/server/discovery#agent_configuration'
+          get '/.well-known/kiosk.json',          to: 'kiosk/server/discovery#kiosk_json'
+          get '/.well-known/api-catalog',         to: 'kiosk/server/discovery#api_catalog'
+        end
+      end
+
+      routes do
+        # The wire's reserved endpoints. The mount is drawn first in the host's
+        # routes, so these win by first-match. Optional modules are drawn
+        # unconditionally and answer `module_not_served` (501) when not configured.
+        # `schema` resolves no identity — it is PUBLIC, like `openapi.json`
+        get  'schema', to: 'wire#schema'
+        post 'pay',    to: 'wire#pay'
+
+        post 'payment_setup',        to: 'verb#create', defaults: { kiosk_verb: 'payment_setup' }
+        get  'payment_setup/return', to: 'payment_setup#show'
+
+        # Our own cable app, so a host's Action Cable config is never touched.
+        # `events` is also in {HandlerMixin::RESERVED_NAMES}; keep the two in step.
+        mount Kiosk::Server::EventsCable::RACK_APP => 'events', internal: true, anchor: true, as: :kiosk_events
+
+        get  'auth/challenge', to: 'auth#challenge'
+        post 'auth/register',  to: 'auth#register'
+        post 'auth/login',     to: 'auth#login'
+        post 'auth/revoke',    to: 'auth#revoke'
+
+        # JWKS sits under the mount, not the origin root.
+        get '.well-known/jwks.json', to: 'jwks#show'
+
+        # Drawn here so the literal `.json` path wins over the verb routes.
+        get 'openapi.json', to: 'open_api#show'
+
+        post 'agents/kyc', to: 'kyc_attestation#create'
+
+        post 'request_kyc',  to: 'verb#create', defaults: { kiosk_verb: 'request_kyc' }
+        post 'kyc/callback', to: 'kyc_callback#create'
+
+        # RFC 8628 device flow.
+        post 'oauth/device_authorization', to: 'oauth_device_authorization#create'
+        post 'oauth/token',                to: 'oauth_token#create'
+        get  'oauth/device/verify',        to: 'device_verify#show'
+        post 'oauth/device/verify',        to: 'device_verify#create'
+
+        post 'auth/link',   to: 'auth#link'
+        post 'auth/claim',  to: 'auth#claim'
+        post 'auth/unlink', to: 'auth#unlink'
+
+        get  'auth/assistants',        to: 'assistants#show'
+        post 'auth/assistants/link',   to: 'assistants#link'
+        post 'auth/assistants/update', to: 'assistants#update'
+        post 'auth/assistants/unlink', to: 'assistants#unlink'
+
+        # The operator routes its own verbs with `kiosk do … end` in config/routes.rb.
+      end
+    end
+  end
+end

data/lib/kiosk/server/errors.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The wire error contract: the closed `code` vocabulary and the problem
+    # document (RFC 9457) every refusal is rendered as.
+    module Errors
+      # The wire's seventeen refusal codes and their HTTP status (spec §9). Adding one is a spec change first.
+      CODES = {
+        'bad_request' => 400,
+        'unauthenticated' => 401,
+        'pow_required' => 402,
+        'payment_setup_required' => 402,
+        'payment_failed' => 402,
+        'forbidden' => 403,
+        'rls_denied' => 403,
+        'spending_cap_exceeded' => 403,
+        'kyc_required' => 403,
+        'verb_not_found' => 404,
+        'not_found' => 404,
+        'method_not_allowed' => 405,
+        'conflict' => 409,
+        'quota_exceeded' => 429,
+        'action_failed' => 500,
+        'internal_error' => 500,
+        'module_not_served' => 501
+      }.freeze
+
+      # RFC 9457 `title`: constant per code; the incident goes in `detail`.
+      TITLES = {
+        'bad_request' => 'Malformed request',
+        'unauthenticated' => 'Not authenticated',
+        'pow_required' => 'Proof-of-work required',
+        'payment_setup_required' => 'Payment setup required',
+        'payment_failed' => 'Payment failed',
+        'forbidden' => 'Forbidden',
+        'rls_denied' => 'Row-level security denied the statement',
+        'spending_cap_exceeded' => 'Spending cap exceeded',
+        'kyc_required' => 'KYC attestation required',
+        'verb_not_found' => 'No such verb',
+        'not_found' => 'Not found',
+        'method_not_allowed' => 'Method not allowed',
+        'conflict' => 'State conflict',
+        'quota_exceeded' => 'Quota exceeded',
+        'action_failed' => 'Action failed',
+        'internal_error' => 'Internal error',
+        'module_not_served' => 'Module not served'
+      }.freeze
+
+      # An identifier, not a page: clients branch on `code`, never on this URI.
+      PROBLEM_TYPE_BASE = 'https://kiosk.tech/problems/'
+
+      PROBLEM_CONTENT_TYPE = 'application/problem+json'
+
+      def self.problem_type(code) = "#{PROBLEM_TYPE_BASE}#{code}"
+
+      def self.problem_title(code) = TITLES.fetch(code, code)
+
+      # The code a bare status (rendered, or from Rails' `rescue_responses`) maps to.
+      # 402 and 500 are absent: several codes share each, so a handler names the code.
+      # 501 is absent: `module_not_served` is raised by name, never inferred.
+      # 404 is `not_found`: `verb_not_found` is raised by the registry before any handler runs.
+      STATUS_CODES = {
+        400 => 'bad_request',
+        401 => 'unauthenticated',
+        403 => 'forbidden',
+        404 => 'not_found',
+        405 => 'method_not_allowed',
+        409 => 'conflict',
+        422 => 'bad_request',
+        429 => 'quota_exceeded'
+      }.freeze
+
+      # The hint for a verb name nothing registered: the names that are.
+      module UnknownName
+        MAX_NAMES = 20
+        PLURALS = { 'query' => 'queries', 'action' => 'actions' }.freeze
+
+        def self.hint(name, verb, names)
+          "unknown #{verb} '#{name}'. #{available(verb, names)} Call GET .../schema for the full catalog."
+        end
+
+        def self.available(verb, names)
+          return "No #{PLURALS.fetch(verb, "#{verb}s")} are registered." if names.empty?
+
+          listed = names.first(MAX_NAMES).join(', ')
+          listed += ', …' if names.size > MAX_NAMES
+          "Available: #{listed}."
+        end
+      end
+
+      #   Errors.unknown_name_hint("listings", "query", %w[browse_listings listing_detail])
+      #   # => "unknown query 'listings'. Available: browse_listings, listing_detail. " \
+      #   #    "Call GET .../schema for the full catalog."
+      def self.unknown_name_hint(name, verb, names) = UnknownName.hint(name, verb, names)
+
+      # The two malformed-request sentences are built here and nowhere else;
+      # an exception's or a parser's own message never reaches `detail`.
+
+      # @param err [KeyError, #to_s] the rescued `KeyError`, or the field name
+      def self.missing_field(err, hint: nil)
+        name = err.is_a?(::KeyError) ? key_of(err) : err
+        return BadRequest.new("missing field: #{name}", hint: hint) if name
+
+        # A hand-raised KeyError carries no key.
+        BadRequest.new('request is missing a required field', hint: hint)
+      end
+
+      def self.key_of(err)
+        err.key.to_s
+      rescue ::ArgumentError
+        nil
+      end
+
+      MALFORMED_JSON_HINT = 'the request body must be a single well-formed JSON object'
+
+      def self.malformed_json(hint: MALFORMED_JSON_HINT)
+        BadRequest.new('invalid JSON body', hint: hint)
+      end
+
+      # What a Rails-native raise answers with: our sentence for the decided code.
+      # The exception's own text goes to the operator's log, never to the wire.
+      # One entry per {STATUS_CODES} value.
+      module Rescued
+        DETAILS = {
+          'bad_request' => 'rejected the request as malformed',
+          'unauthenticated' => 'requires a credential this request did not carry',
+          'forbidden' => 'refused the request',
+          'not_found' => 'found no such record',
+          'method_not_allowed' => 'does not accept the request as sent',
+          'conflict' => 'refused the request as conflicting with current state',
+          'quota_exceeded' => 'refused the request because a quota is exhausted'
+        }.freeze
+
+        HINTS = {
+          'bad_request' => "check the arguments against this verb's input_schema — " \
+                           'GET .../schema publishes it.',
+          'unauthenticated' => 'present a valid access token for this origin and retry.',
+          'forbidden' => 'this principal may not make this call; retrying it unchanged ' \
+                         'will be refused again.',
+          'not_found' => 'an argument names something this origin does not have; ' \
+                         're-read it from a query before retrying.',
+          'method_not_allowed' => 'a query is GET .../<query-name> and an action is ' \
+                                  'POST .../<action-name>; GET .../schema says which each verb is.',
+          'conflict' => 'the state moved under you; re-read it with a query and retry ' \
+                        'with what it says.',
+          'quota_exceeded' => 'the operator sets this quota; wait before retrying.'
+        }.freeze
+
+        def self.wire(code, verb)
+          subject = verb.nil? || verb.to_s.empty? ? 'this verb' : "verb #{verb.to_s.inspect}"
+          { code: code, message: "#{subject} #{DETAILS.fetch(code)}", hint: HINTS.fetch(code) }
+        end
+      end
+
+      RESCUED_DETAILS = Rescued::DETAILS
+      RESCUED_HINTS = Rescued::HINTS
+
+      # @return [Hash] `{code:, message:, hint:}` of the wire error a rescued exception becomes
+      def self.rescued_wire(code, verb: nil) = Rescued.wire(code, verb)
+
+      class Base < StandardError
+        CODE        = 'internal_error'
+        HTTP_STATUS = 500
+
+        attr_reader :hint
+
+        def initialize(message = nil, hint: nil)
+          super(message)
+          @hint = hint
+        end
+
+        def code        = self.class.const_get(:CODE)
+        def http_status = self.class.const_get(:HTTP_STATUS)
+
+        # Problem-document members beyond `code`/`message`/`hint`.
+        def extensions = {}
+
+        def response_headers = {}
+
+        # `code` is a top-level extension member (RFC 9457 §3.2): the one field a client branches on.
+        def to_problem
+          {
+            type: Errors.problem_type(code),
+            title: Errors.problem_title(code),
+            status: http_status,
+            detail: message,
+            code: code,
+            hint: hint
+          }.merge(extensions).compact
+        end
+      end
+
+      # A wire error named by its code rather than its class. `extra:` adds extension members;
+      # the members the code and message decide stay theirs, and `instance` is never emitted (§9).
+      class WireError < Base
+        DECIDED = %i[type title status detail instance code hint].freeze
+
+        def initialize(message = nil, code:, hint: nil, extra: nil)
+          code = code.to_s
+          unless CODES.key?(code)
+            raise ArgumentError,
+                  "unknown wire code #{code.inspect} — the vocabulary is Errors::CODES, closed by the spec"
+          end
+
+          super(message, hint: hint)
+          @wire_code = code
+          @extra     = extensions_for(code, extra || {})
+        end
+
+        def code        = @wire_code
+        def http_status = CODES.fetch(@wire_code)
+        def extensions  = @extra
+
+        private
+
+        # `challenges` appears only on `pow_required` (§9).
+        def extensions_for(code, extra)
+          extra = extra.except(*DECIDED)
+          code == 'pow_required' ? extra : extra.except(:challenges)
+        end
+      end
+
+      class BadRequest < Base
+        CODE        = 'bad_request'
+        HTTP_STATUS = 400
+      end
+
+      class Unauthenticated < Base
+        CODE        = 'unauthenticated'
+        HTTP_STATUS = 401
+      end
+
+      class Forbidden < Base
+        CODE        = 'forbidden'
+        HTTP_STATUS = 403
+      end
+
+      # An argument names something absent (§9.1 rule 2); an unknown verb is {VerbNotFound}.
+      class NotFound < Base
+        CODE        = 'not_found'
+        HTTP_STATUS = 404
+      end
+
+      # No verb by that name is registered; the hint lists the ones that are.
+      class VerbNotFound < Base
+        CODE        = 'verb_not_found'
+        HTTP_STATUS = 404
+      end
+
+      # The verb exists but not for this HTTP method.
+      class MethodNotAllowed < Base
+        CODE        = 'method_not_allowed'
+        HTTP_STATUS = 405
+
+        attr_reader :allow
+
+        def initialize(message = nil, allow:, hint: nil)
+          super(message, hint: hint)
+          @allow = allow.to_s
+        end
+
+        def response_headers = { 'Allow' => allow }
+      end
+
+      class Conflict < Base
+        CODE        = 'conflict'
+        HTTP_STATUS = 409
+      end
+
+      class RLSDenied < Base
+        CODE        = 'rls_denied'
+        HTTP_STATUS = 403
+      end
+
+      # The acting assistant's spending cap would be exceeded; checked before capture.
+      class SpendingCapExceeded < Base
+        CODE        = 'spending_cap_exceeded'
+        HTTP_STATUS = 403
+      end
+
+      class KycRequired < Base
+        CODE        = 'kyc_required'
+        HTTP_STATUS = 403
+      end
+
+      # The operator's handler raised; `internal_error` is the platform's own failure.
+      class ActionFailed < Base
+        CODE        = 'action_failed'
+        HTTP_STATUS = 500
+      end
+
+      class PaymentSetupRequired < Base
+        CODE        = 'payment_setup_required'
+        HTTP_STATUS = 402
+
+        def initialize(message = 'payment setup required',
+                       hint: 'call payment_setup to obtain a card setup link')
+          super
+        end
+      end
+
+      # The charge did not settle. The adapter supplies a human-safe message, never the PSP's.
+      class PaymentFailed < Base
+        CODE        = 'payment_failed'
+        HTTP_STATUS = 402
+
+        def initialize(message = 'payment failed',
+                       hint: 'the charge did not settle; verify via my_orders before retrying')
+          super
+        end
+      end
+
+      class PowRequired < Base
+        CODE        = 'pow_required'
+        HTTP_STATUS = 402
+
+        attr_reader :challenges
+
+        def initialize(challenges:)
+          super('proof-of-work required')
+          @challenges = challenges
+        end
+
+        def extensions = { challenges: challenges }
+      end
+
+      # This origin does not serve the optional module the path reaches (§6, §11, §12).
+      # `message` names the module.
+      class ModuleNotServed < Base
+        CODE        = 'module_not_served'
+        HTTP_STATUS = 501
+      end
+
+      # Raised when an optional feature is called, not at boot.
+      class ConfigurationError < StandardError; end
+    end
+  end
+end

data/lib/kiosk/server/event_stores.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    module EventStores
+      # The default event store: the `<schema>.events` table, shared by every process on the database.
+      class ActiveRecord
+        # The published retention floor: at least this much history per identity.
+        DEFAULT_RETENTION_HOURS = 24
+
+        # Seconds between opportunistic retention sweeps.
+        DEFAULT_PRUNE_INTERVAL = 300
+
+        # Retention is by time only; a row-count ceiling would become the real
+        # retention on a busy subject.
+        def initialize(retention_hours: DEFAULT_RETENTION_HOURS,
+                       prune_interval: DEFAULT_PRUNE_INTERVAL)
+          @retention_hours = retention_hours
+          @prune_interval  = prune_interval
+          @last_prune_at   = 0
+          @mutex           = Mutex.new
+        end
+
+        # `event` is string-keyed, without "id"; returns the id the sequence assigned.
+        def append(identity_key, event)
+          prune_if_due!
+
+          binds = [identity_key.to_s, event['topic'], event['subject'],
+                   event['occurred_at'], JSON.generate(event['data'])]
+          rows = connection.exec_query(insert_sql, 'Kiosk events append', binds).to_a
+          rows.first['id'].to_i
+        end
+
+        # This identity's events after the cursor `id`, ascending.
+        def since(identity_key, id)
+          sql = <<~SQL.squish
+            SELECT id, topic, subject, occurred_at, data
+            FROM #{table}
+            WHERE identity_key = $1 AND id > $2
+            ORDER BY id ASC
+          SQL
+          connection.exec_query(sql, 'Kiosk events since', [identity_key.to_s, id.to_i])
+                    .to_a.map { |row| to_event(row) }
+        end
+
+        # The origin's maximum id, 0 when empty.
+        def head
+          row = connection.exec_query(
+            %(SELECT COALESCE(MAX(id), 0) AS head FROM #{table}), 'Kiosk events head'
+          ).to_a.first
+          row['head'].to_i
+        end
+
+        # True when rows after the caller's cursor were swept; a cursor at or
+        # past the newest row missed nothing.
+        def truncated?(_identity_key, id)
+          row = connection.exec_query(
+            %(SELECT COALESCE(MIN(id), 0) AS floor, COALESCE(MAX(id), 0) AS head FROM #{table}),
+            'Kiosk events floor'
+          ).to_a.first
+          return false if row['head'].to_i <= id.to_i
+
+          row['floor'].to_i > id.to_i + 1
+        end
+
+        # Deletes everything older than the retention window; {#append} calls
+        # it at most once per +prune_interval+ per process.
+        def prune!
+          connection.exec_query(
+            %(DELETE FROM #{table} WHERE created_at < now() - ($1 || ' hours')::interval),
+            'Kiosk events prune', [@retention_hours.to_s]
+          )
+          nil
+        end
+
+        private
+
+        def insert_sql
+          <<~SQL.squish
+            INSERT INTO #{table} (identity_key, topic, subject, occurred_at, data)
+            VALUES ($1, $2, $3, $4, $5)
+            RETURNING id
+          SQL
+        end
+
+        # The wire's five event members, string-keyed, as {EventStore} gives them.
+        def to_event(row)
+          {
+            'id' => row['id'].to_i,
+            'topic' => row['topic'],
+            'subject' => row['subject'],
+            'occurred_at' => as_iso8601(row['occurred_at']),
+            'data' => row['data'].is_a?(String) ? JSON.parse(row['data']) : row['data']
+          }
+        end
+
+        # The adapter may return a Time or a String.
+        def as_iso8601(value)
+          return value.utc.strftime('%Y-%m-%dT%H:%M:%SZ') if value.respond_to?(:utc)
+
+          Time.parse(value.to_s).utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+        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 table = %("#{Kiosk.configuration.schema}".events)
+
+        # `connection` raises under `permanent_connection_checkout = :disallowed`.
+        def connection = ::ActiveRecord::Base.lease_connection
+      end
+    end
+  end
+end