kiosk-server 0.5.20

data/lib/generators/kiosk/install/templates/create_kiosk_auth_challenges.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration 010 — create kiosk.auth_challenges.
+# Each public key's outstanding auth challenge, so a challenge issued by one
+# process is redeemed by any other (AuthChallengeStores::ActiveRecord, the default).
+class CreateKioskAuthChallenges < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:auth_challenge) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".auth_challenges)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_device_authorizations.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Migration 004 — kiosk.device_authorizations: the account-binding state
+# machine behind the RFC 8628-shaped claim and link ceremonies, in the shape
+# DeviceAuthorizationStores::ActiveRecord reads and writes (hashed device and
+# user codes, the bound public key, claim vs link).
+class CreateKioskDeviceAuthorizations < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:device_authorizations, user_id_type: user_id_type) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".device_authorizations)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_events.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Migration 007 — create kiosk.events.
+# The per-identity EVENT TAIL an operator serving any topic needs. `id` is a
+# bigserial, and that is what makes the wire's event id a per-origin monotonic
+# integer — one cursor then resumes every subscription on a socket with one
+# integer comparison.
+# `identity_key` is a user_id, not an agent_id: a human's second assistant must
+# read the same tail, and a revoked assistant is stopped at the socket.
+# Laid down unconditionally, like kiosk.kyc_attributes: the route is drawn
+# whether or not this origin declares a topic, and an empty table costs nothing.
+class CreateKioskEvents < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:events) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".events)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_identity_tables.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration 002 — Kiosk identity tables: agents, agent_tokens, agent_mappings.
+class CreateKioskIdentityTables < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:identity_tables, user_id_type: user_id_type, user_table: options[:user_table]) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".agent_mappings)
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".agent_tokens)
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".agents)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_kyc_attributes.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Migration 006 — create kiosk.kyc_attributes.
+# ONE ROW per NAMED ANONYMIZED boolean attribute a valid KYC attestation
+# granted an agent (e.g. age_over_18, licence_a). Only the NAMES are stored —
+# never the DOB, licence number, or any underlying document.
+# There is no value column: the grant IS the row, so every gate is an EXISTS
+# and no reader has to decide which spelling of `true` counts.
+# Additive/opt-in: needed only if an Action gates on specific KYC attributes.
+class CreateKioskKycAttributes < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:kyc_attributes, user_id_type: user_id_type, user_table: options[:user_table]) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".kyc_attributes)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_mandates.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Migration 005 — kiosk AP2 mandate trail:
+# intent_mandates, cart_mandates, payment_mandates, settlements.
+# See the Payment (AP2 mandate chain) section of the spec.
+class CreateKioskMandates < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:mandates, user_id_type: user_id_type) %>
+    SQL
+  end
+
+  def down
+    # Reverse-FK order: payment_mandates and settlements both reference
+    # cart_mandates, so both drop before it; cart_mandates before intent_mandates.
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".payment_mandates)
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".settlements)
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".cart_mandates)
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".intent_mandates)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_pow_spent.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration 008 — create kiosk.pow_spent.
+# The spent proof-of-work challenge ids, so a proof is accepted once across
+# every process and every deploy (PowSpentStores::ActiveRecord, the default).
+class CreateKioskPowSpent < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:pow_spent) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".pow_spent)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_refunds.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration 012 — create kiosk.refunds.
+# The refunds of settled charges (Kiosk::Server::PaymentClaim#refund), which
+# recent spend leaves out of the proof-of-work toll.
+class CreateKioskRefunds < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:refunds) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".refunds)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_revocations.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration 009 — create kiosk.revocations.
+# Each agent's token revocation watermark, so a revoke or an unlink holds in
+# every process and across restarts (RevocationStores::ActiveRecord, the default).
+class CreateKioskRevocations < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:revocations) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".revocations)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_schema.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Migration 001 — Kiosk schema + the four current_*() helper functions.
+#
+# `ActiveRecord::Migration[…]` resolves at host-app load time, so this
+# file picks up whatever Rails version the host is on.
+class CreateKioskSchema < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:helper_functions, guc_namespace: options[:guc_namespace], user_id_type: user_id_type) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP SCHEMA IF EXISTS "<%= options[:schema] %>" CASCADE)
+  end
+end

data/lib/generators/kiosk/install/templates/create_kiosk_visits.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Migration 011 — create kiosk.visits.
+# The visits the operator records as fulfilled (Kiosk::Visit.record!), which
+# lower the proof-of-work toll for a returning customer.
+class CreateKioskVisits < ActiveRecord::Migration[ActiveRecord::Migration.current_version]
+  def up
+    execute <<~'SQL'
+<%= ddl(:visits, user_id_type: user_id_type) %>
+    SQL
+  end
+
+  def down
+    execute %(DROP TABLE IF EXISTS "<%= options[:schema] %>".visits)
+  end
+end

data/lib/generators/kiosk/install/templates/initializer.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Kiosk configuration. Every option: https://kiosk.tech and the kiosk-server README.
+
+Kiosk.configure do |c|
+  # Your user model class name, resolved at request time.
+  c.user_model     = "<%= options[:user_table].classify %>"
+
+  # Type of users.id: :uuid (default), :bigint, :integer or :text.
+  c.user_id_type   = :<%= options[:user_id_type] %>
+
+  # coerce-then-validate on the per-verb wire is UNCONDITIONAL: arguments are
+  # always checked against the verb's `input_schema` (§8.1). This flag adds a check:
+  # it validates every answer against the verb's `output_schema`. Off in production,
+  # where a descriptor typo would become a 500 for a caller.
+  c.validate_responses = !Rails.env.production?
+
+  # GUC namespace for SET LOCAL (and RLS policies). Default "app".
+  # c.guc_namespace = "<%= options[:guc_namespace] %>"
+
+  # Postgres schema for Kiosk helper functions and tables.
+  # c.schema = "<%= options[:schema] %>"
+
+  # Opt-in Postgres RLS: add `gem "kiosk-rls"` and create these database roles yourself.
+  # c.app_role        = "app_role"      # runtime role with NOBYPASSRLS
+  # c.enforce_db_role = true            # SET LOCAL ROLE app_role per request
+
+  # The exact origin assistants dial (scheme + host, no trailing slash); it must
+  # match `kiosk.issuer` in /.well-known/kiosk.json, or every proof is rejected.
+  # c.issuer = "https://<your-host>"
+
+  # Further origins this deployment serves, each its own operator.
+  # c.additional_origins = ["https://<another-host>"]
+
+  # Role vocabulary; set together with `registration_role`. Your `user_idp` must
+  # resolve a role for every human who can approve a binding (§6.3).
+  # c.roles = %i[customer]
+
+  # The default role for self-registered assistants and role-less bindings; your least-privileged one.
+  # c.registration_role = :customer
+
+  # Owner block surfaced in /.well-known/kiosk.json.
+  # c.owner = { name: "Your Company", support: "support@example.com" }
+
+  # Optional: an agent IdP of your own (subclass Kiosk::AgentIdentityProviders::Base; agent ids must be UUIDs).
+  # c.agent_idp = MyExternalAgentIdp.new
+
+  # Optional: a user IdP binding your signed-in humans, e.g. `gem "kiosk-user-idp-devise"`.
+  # c.user_idp = Kiosk::UserIdentityProviders::Devise.new
+
+  # Optional audit sink: one ActionEvent per action, arguments in full and unredacted.
+  # c.audit_sink = ->(e) { Rails.logger.info(e.with_arg_types.to_h.to_json) }
+end

data/lib/kiosk/handler.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kiosk
+  # Include into any controller to declare verbs: a query (`GET <mount>/<name>`)
+  # or an action (`POST <mount>/<name>`). Handlers live in app/controllers/kiosk.
+  #
+  #   class Kiosk::BoardController < ActionController::API
+  #     include Kiosk::Handler
+  #
+  #     kind :query
+  #     description "Lists what this shop has in stock right now, so the " \
+  #                 "assistant can decide what to put in a basket."
+  #     input_schema type: "object", additionalProperties: false,
+  #                  properties: { q: { type: "string" } }
+  #     output_schema type: "array",
+  #                   items: { type: "object",
+  #                            properties: { sku:         { type: "string" },
+  #                                          price_cents: { type: "integer" } } }
+  #     def catalog
+  #       render json: Product.in_stock.search(params[:q]).as_json
+  #     end
+  #
+  #     kind :action
+  #     description "Places an order for the assistant's human. Returns the " \
+  #                 "order and what it will cost; nothing is charged until `pay`."
+  #     input_schema type: "object", additionalProperties: false,
+  #                  properties: { items: { type: "array", items: { type: "object" } } },
+  #                  required: %w[items]
+  #     output_schema type: "object",
+  #                   properties: { order_id:    { type: "string" },
+  #                                 total_cents: { type: "integer" } }
+  #     def create_order
+  #       order = Orders::Place.call(user_id: kiosk_identity.user_id, params: params)
+  #       render json: { order_id: order.id, total_cents: order.total_cents }
+  #     end
+  #   end
+  module Handler
+    def self.included(base)
+      Kiosk::Server::HandlerMixin.install(base)
+      Kiosk::Server::HandlerRegistrations.add(base)
+    end
+  end
+end

data/lib/kiosk/owned.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Kiosk
+  # `include Kiosk::Owned` in a model with a `user_id` column gives it `own`,
+  # the current principal's rows: `Order.own.find(id)`, and `owned_by(user_id)`,
+  # one principal's rows. `user_id` holds `Kiosk.current_user_id`.
+  module Owned
+    extend ActiveSupport::Concern
+
+    included do
+      scope :owned_by, ->(user_id) { where(user_id:) }
+      scope :own, -> { owned_by(Kiosk.current_user_id) }
+    end
+  end
+end

data/lib/kiosk/payable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Kiosk
+  # `include Kiosk::Payable` in the model that `Kiosk::Server::PaymentClaim`
+  # names. It gives the row its `payment_state`, the `cart` an assistant signs
+  # to pay for it, and the `settlement` that paid it.
+  module Payable
+    extend ActiveSupport::Concern
+
+    UNPAID   = 'unpaid'
+    PENDING  = 'pending'
+    PAID     = 'paid'
+    REFUNDED = 'refunded'
+
+    # The `payment_state` member of a per-user query's row.
+    STATE_SCHEMA = {
+      type: 'string', enum: [UNPAID, PENDING, PAID, REFUNDED],
+      description: '`unpaid`: nothing is charged; pay for it. `pending`: a charge is in progress and can ' \
+                   'already have taken the money; read again, do not pay again. `paid`: charged. ' \
+                   '`refunded`: the charge went back to the card.'
+    }.freeze
+
+    # The `cart` member of the answer of an action that creates a payable row.
+    CART_SCHEMA = {
+      type: 'object', additionalProperties: false,
+      description: 'Sign the cart mandate with these three values, unchanged.',
+      properties: {
+        currency: { type: 'string' },
+        total_amount_cents: { type: 'integer' },
+        line_items: { type: 'array', items: { type: 'object' } }
+      },
+      required: %w[currency total_amount_cents line_items]
+    }.freeze
+
+    class_methods do
+      # Adds `settled_currency`, the currency of a settlement among `settlements`
+      # whose cart names the row, or NULL: the caller's own on the wire, all of
+      # them in a back office.
+      def with_settlement(settlements)
+        select(arel_table[Arel.star],
+               Arel::Nodes::Grouping.new(settlements.joins(:cart_mandate).where(names_row).select(:currency)
+                                                    .limit(1).arel).as('settled_currency'))
+      end
+
+      def payment_claim = Kiosk.configuration.payment_provider
+
+      private
+
+      # `cart_mandates.line_items @> [{"<reference>": "<this row's id>"}]`.
+      def names_row
+        line = Arel::Nodes::NamedFunction.new(
+          'jsonb_build_object', [Arel::Nodes.build_quoted(payment_claim.reference),
+                                 Arel::Nodes::NamedFunction.new('CAST', [arel_table[:id].as(Arel.sql('text'))])]
+        )
+        Arel::Nodes::InfixOperation.new('@>', Kiosk::CartMandate.arel_table[:line_items],
+                                        Arel::Nodes::NamedFunction.new('jsonb_build_array', [line]))
+      end
+    end
+
+    # `pending` means a capture is in flight: the caller reads again and does
+    # not sign a new mandate. A row read without `with_settlement` asks the
+    # settlements itself.
+    def payment_state
+      status = self[:payment_status]
+      return REFUNDED if status == REFUNDED
+      return PAID     if status == PAID || settled?
+      return PENDING  if status == Kiosk::Server::PaymentClaim::PAYING
+
+      UNPAID
+    end
+
+    # The cart that pays for this row: a line naming the row, then `lines`,
+    # each `{qty:, price_cents:, ...}`, which sum to the total.
+    def cart(lines)
+      claim = self.class.payment_claim
+      { currency: claim.currency,
+        total_amount_cents: lines.sum { it[:qty] * it[:price_cents] },
+        line_items: [{ claim.reference => id }, *lines] }
+    end
+
+    # The first settlement whose cart names this row, or nil.
+    def settlement = self.class.payment_claim.settlements(id).order(:created_at).first
+
+    private
+
+    def settled? = has_attribute?(:settled_currency) ? !settled_currency.nil? : !settlement.nil?
+  end
+end

data/lib/kiosk/server/account_binding.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Binds a proven public key to a human's account. A fresh key gets a new
+    # linked agent row; a known key is rebound, keeping its agent_id and
+    # reputation and adopting the new holder's role.
+    module AccountBinding
+      module_function
+
+      # Call only after possession of `public_key_pem` has been proven.
+      # `requested_role` always comes from a human's identity, never the wire.
+      #
+      # @return [Hash] { agent_id:, user_id:, access_token:, fresh: }
+      def bind!(public_key_pem:, user_id:, requested_role: nil)
+        config = Kiosk.configuration
+        pem    = public_key_pem.to_s.strip
+        raise ArgumentError, 'user_id required' if user_id.nil? || user_id.to_s.empty?
+
+        warn_role_resolution_not_total(config, requested_role)
+
+        # `lease_connection`: the operator's hooks must share this transaction.
+        conn = ::ActiveRecord::Base.lease_connection
+        existing = Rows.live_by_key(conn, config.schema, pem)
+        return rebind(conn, config, existing, user_id, requested_role) if existing
+
+        register_linked(conn, config, pem, user_id, requested_role)
+      end
+
+      # Revokes `agent_id`'s binding, which must belong to `user_id`; its tokens
+      # stop verifying and its `/auth/login` is denied.
+      #
+      # @raise [Errors::NotFound] when no live agent row matches the pair.
+      def unlink!(agent_id:, user_id:)
+        config = Kiosk.configuration
+        raise Errors::BadRequest, 'agent_id required' if agent_id.nil? || agent_id.to_s.empty?
+
+        # The ownership predicate is the security boundary: both values are binds.
+        raise not_linked unless Rows.revoke_owned(::ActiveRecord::Base.lease_connection, config.schema, agent_id, user_id)
+
+        revoke_tokens(config, agent_id)
+        config.assistant_unlinked&.call(agent: agent_id, account: config.user_model.constantize.find(user_id))
+        { agent_id: agent_id }
+      end
+
+      ROLE_NOT_TOTAL =
+        '[kiosk-server] an account-binding ceremony resolved NO role for the approving ' \
+        'human, and this origin declares more than one role ' \
+        '(%<roles>s). Role resolution must be TOTAL: an operator that ' \
+        'assigns roles at all assigns one to EVERY human who can approve a binding. A ' \
+        'role for staff and nothing for customers is not a supported configuration — ' \
+        'this binding lands on %<role>s, the role registration would assign, so a human ' \
+        'who should hold a privileged one gets an assistant ' \
+        'that cannot act for them. Fix the identity system, not the ceremony: a ' \
+        '`#kiosk_role` that can answer nil is the usual cause, and returning the ' \
+        'least-privileged declared role instead makes it total.'
+      private_constant :ROLE_NOT_TOTAL
+
+      class << self
+        private
+
+        # Known key: remap the holder and role, keep agent_id and reputation.
+        # The role is never read from the row: it belonged to the previous holder.
+        def rebind(conn, config, existing, user_id, requested_role = nil)
+          agent_id = existing.fetch('id')
+          previous = existing.fetch('user_id')
+          role     = resolved_role(config, requested_role)
+          # The same holder still gets the role remap and revocation; only the hook is skipped.
+          transition = previous.to_s != user_id.to_s
+          conn.transaction do
+            Rows.rebind(conn, config.schema, agent_id, user_id, role)
+            claimed(config, agent_id, previous, user_id) if transition && config.assistant_claimed
+          end
+          # The old holder's tokens die (§6.3). The IdP dates new mints at the
+          # watermark, so the token minted below survives it.
+          revoke_tokens(config, agent_id)
+          { agent_id: agent_id, user_id: user_id.to_s, access_token: issue_token(agent_id, role), fresh: false }
+        end
+
+        # Next second: JWT `iat` is whole seconds and the check is `iat < watermark` (§6.3).
+        def revoke_tokens(config, agent_id)
+          config.revocation_store.revoke_all(agent_id, at: Time.now.to_i + 1)
+        end
+
+        def claimed(config, agent_id, previous, user_id)
+          accounts = config.user_model.constantize
+          config.assistant_claimed.call(agent: agent_id, from: accounts.find(previous), to: accounts.find(user_id))
+        end
+
+        # Fresh key: a new linked agent row under the approving human.
+        def register_linked(conn, config, pem, user_id, requested_role)
+          role = resolved_role(config, requested_role)
+          agent_id = conn.transaction { Rows.insert_linked(conn, config.schema, user_id, pem, role) }
+          { agent_id: agent_id, user_id: user_id.to_s, access_token: issue_token(agent_id, role), fresh: true }
+        end
+
+        def not_linked
+          Errors::NotFound.new(
+            'no linked assistant account with this agent_id',
+            hint: 'only assistant accounts bound to the signed-in account can be unlinked'
+          )
+        end
+
+        # The ceremony's role, else the operator's default; never the key's previous role.
+        def resolved_role(config, requested_role)
+          validated_role(config, requested_role || config.registration_role)
+        end
+
+        # Rejects a role outside `config.roles`.
+        def validated_role(config, candidate)
+          role = candidate&.to_s
+          role = nil if role && role.empty?
+          if role && config.roles.map(&:to_s).exclude?(role)
+            raise Errors::ConfigurationError,
+                  "binding role #{role.inspect} is not among configured roles #{config.roles.inspect}"
+          end
+          role
+        end
+
+        # An origin with several roles must resolve one for every approving human (§6.3).
+        def warn_role_resolution_not_total(config, requested_role)
+          return unless requested_role.nil? || requested_role.to_s.strip.empty?
+          return unless config.roles.to_a.size > 1
+
+          log_warning(format(ROLE_NOT_TOTAL, roles: config.roles.inspect, role: config.registration_role.inspect))
+        end
+
+        # Rails.logger is nil before the host app boots.
+        def log_warning(message)
+          logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+          logger ? logger.warn(message) : Kernel.warn(message)
+        end
+
+        def issue_token(agent_id, role)
+          AgentIdentityProviders::DefaultAgentIdp.new.issue(agent_id: agent_id, role: role)
+        end
+      end
+
+      # The agents-table statements a binding runs.
+      module Rows
+        module_function
+
+        def live_by_key(conn, schema, pem)
+          conn.exec_query(<<~SQL.squish, 'Kiosk agent lookup by key', [pem, Kiosk.current_issuer]).to_a.first
+            SELECT id, user_id FROM #{schema}.agents
+            WHERE public_key = $1 AND issuer = $2 AND revoked_at IS NULL
+            LIMIT 1
+          SQL
+        end
+
+        def revoke_owned(conn, schema, agent_id, user_id)
+          conn.exec_query(<<~SQL.squish, 'Kiosk agent unlink', [agent_id, user_id, Kiosk.current_issuer]).to_a.first
+            UPDATE #{schema}.agents
+            SET revoked_at = now()
+            WHERE id = $1
+              AND user_id = $2
+              AND issuer = $3
+              AND revoked_at IS NULL
+            RETURNING id
+          SQL
+        end
+
+        # An empty array cannot travel as a bind, so "no role" is a different statement.
+        def rebind(conn, schema, agent_id, user_id, role)
+          role_set, role_binds =
+            role ? [', allowed_roles = ARRAY[$3]::text[]', [role]] : [", allowed_roles = '{}'::text[]", []]
+          conn.exec_query(<<~SQL.squish, 'Kiosk agent rebind', [user_id, agent_id, *role_binds])
+            UPDATE #{schema}.agents
+            SET user_id = $1#{role_set}
+            WHERE id = $2
+          SQL
+        end
+
+        # The column is NOT NULL: no role is `'{}'`, never NULL.
+        def insert_linked(conn, schema, user_id, pem, role)
+          allowed_roles_sql, role_binds = role ? ['ARRAY[$4]::text[]', [role]] : ["'{}'::text[]", []]
+          rows = conn.exec_query(<<~SQL.squish, 'Kiosk linked agent insert', [user_id, pem, Kiosk.current_issuer, *role_binds])
+            INSERT INTO #{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
+      end
+      private_constant :Rows
+    end
+  end
+end

data/lib/kiosk/server/account_holder_gate.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Requires a human signed in through the operator's own session
+    # (`user_idp`), never an agent token. A browser is sent to `sign_in_path`;
+    # any other caller gets a 401 naming where to sign in.
+    module AccountHolderGate
+      private
+
+      # Answers the signed-in identity, or nil after it has answered the request.
+      def require_account_holder!(prompt:, flash_alert:)
+        @identity = Kiosk.configuration.user_idp&.verify(request)
+        refuse_signed_out(prompt, flash_alert) unless @identity
+        @identity
+      end
+
+      def refuse_signed_out(prompt, flash_alert)
+        sign_in_path = Kiosk.configuration.sign_in_path
+        if sign_in_path && html_request?
+          flash_sign_in_alert(flash_alert)
+          store_return_location
+          redirect_to sign_in_path
+        else
+          render plain: sign_in_path ? "#{prompt} #{sign_in_directions(sign_in_path)}" : prompt,
+                 status: :unauthorized
+        end
+      end
+
+      def sign_in_directions(sign_in_path)
+        "Sign in at #{request.base_url}#{sign_in_path} — or open #{request.original_url} " \
+          'in a browser, which goes there and comes back here.'
+      end
+
+      def html_request?
+        return true if request.format.html?
+
+        request.headers['Accept'].to_s.include?('text/html')
+      rescue StandardError
+        false
+      end
+
+      # A host without the flash middleware must still redirect.
+      def flash_sign_in_alert(message)
+        flash[:alert] = message
+      rescue StandardError
+        nil
+      end
+
+      # Devise's return-to key.
+      def store_return_location
+        session['user_return_to'] = request.fullpath
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end