kiosk-server 0.5.20

data/app/controllers/kiosk/server/kyc_callback_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # POST <endpoint>/kyc/callback — the KYC provider reports an approval.
+    # Authenticated by the open request, its nonce and the signed attestation.
+    class KycCallbackController < WireController
+      def create
+        Kyc.served!
+        Kyc.callback(parse_body!)
+        render json: { ok: true }, status: :ok
+      end
+    end
+  end
+end

data/app/controllers/kiosk/server/oauth_device_authorization_controller.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+
+module Kiosk
+  module Server
+    # POST <endpoint>/oauth/device_authorization (RFC 8628 §3.1): an assistant
+    # opens the claim half of account binding with `client_id` and `public_key`.
+    class OauthDeviceAuthorizationController < ::ActionController::API
+      include BindingModuleGate
+
+      prepend_before_action :refuse_unserved_binding
+
+      def create
+        problem = request_problem
+        return render_oauth_error(:invalid_request, problem, status: 400) if problem
+
+        result = DeviceCodeGrant.start(client_id: params[:client_id].to_s, public_key_pem: params[:public_key].to_s)
+        Kiosk::Server::Headers.add_to(response.headers)
+        render json: device_authorization(result)
+      end
+
+      private
+
+      # The first reason this request is refused, or nil.
+      def request_problem
+        return 'client_id parameter required' if params[:client_id].to_s.empty?
+        return 'public_key parameter required' if params[:public_key].to_s.empty?
+
+        key_problem(params[:public_key].to_s) || role_problem
+      end
+
+      def key_problem(public_key)
+        PopVerifier.load_public_key(public_key.strip)
+        nil
+      rescue Errors::BadRequest => e
+        e.message
+      end
+
+      # Refused, not ignored: the role is the approving human's, and this
+      # request is unauthenticated.
+      def role_problem
+        offending = %i[role scope].find { |name| params.key?(name) }
+        return unless offending
+
+        "#{offending} is not accepted here — an assistant does not choose its own role. " \
+          "The role of a bound assistant is the approving account holder's own role, " \
+          "read from this provider's identity system when they approve at the verify page."
+      end
+
+      def device_authorization(result)
+        {
+          device_code: result[:device_code],
+          user_code: result[:user_code],
+          verification_uri: verification_uri,
+          verification_uri_complete: "#{verification_uri}?user_code=#{result[:user_code]}",
+          expires_in: result[:expires_in],
+          interval: result[:interval]
+        }
+      end
+
+      def verification_uri
+        mount = Kiosk.configuration.mount_path
+        "#{request.base_url}#{mount}/oauth/device/verify"
+      end
+
+      def render_oauth_error(code, description, status:)
+        Kiosk::Server::Headers.add_to(response.headers)
+        render json: { error: code.to_s, error_description: description }, status: status
+      end
+    end
+  end
+end

data/app/controllers/kiosk/server/oauth_token_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+
+module Kiosk
+  module Server
+    # POST <endpoint>/oauth/token: the assistant polls the claim ceremony
+    # (RFC 8628 §3.4). Only the device_code grant is served.
+    class OauthTokenController < ::ActionController::API
+      include BindingModuleGate
+      include AuthController::Answers
+      include AuthController::Proofs
+
+      prepend_before_action :refuse_unserved_binding
+
+      UNSUPPORTED_GRANT = 'only the device_code grant is served here — ' \
+                          'kiosk-pop (POST /auth/login) is the token-refresh path'
+
+      def create
+        case params[:grant_type].to_s
+        when DeviceCodeGrant::GRANT_TYPE then handle_device_code_grant
+        when '' then render_oauth_error(:invalid_request, 'grant_type required', status: 400)
+        else render_oauth_error(:unsupported_grant_type, UNSUPPORTED_GRANT, status: 400)
+        end
+      end
+
+      private
+
+      # The auth toll answers with its own problem documents (§10); every other refusal is OAuth's.
+      def handle_device_code_grant
+        result = DeviceCodeGrant.exchange(device_code: params[:device_code].to_s, signed: params[:signed], pow: proofs)
+        Kiosk::Server::Headers.add_to(response.headers)
+        return render json: token_body(result) if result[:ok]
+
+        render_grant_failure(result)
+      rescue Errors::Base => e
+        render_error(e)
+      end
+
+      # RFC 6749 §5.2: invalid_client — the possession proof failed —
+      # is the one error the server SHOULD signal with 401.
+      def render_grant_failure(result)
+        status = result[:error] == 'invalid_client' ? 401 : 400
+        render json: { error: result[:error], error_description: result[:description] }, status: status
+      end
+
+      def token_body(result)
+        body = { access_token: result[:access_token], token_type: result[:token_type], expires_in: result[:expires_in] }
+        body[:scope] = result[:scope] if result[:scope]
+        body
+      end
+
+      def render_oauth_error(code, description, status:)
+        Kiosk::Server::Headers.add_to(response.headers)
+        render json: { error: code.to_s, error_description: description }, status: status
+      end
+    end
+  end
+end

data/app/controllers/kiosk/server/open_api_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+
+module Kiosk
+  module Server
+    # `GET <endpoint>/openapi.json`: public, untolled, cached like `/schema`.
+    class OpenApiController < VerbController
+      # `?v=` is the origin's document version; the ETag is this document's bytes.
+      def show
+        render_public_document(
+          OpenApi.json(base_url: request.base_url),
+          version: SchemaDocument.digest,
+          etag: OpenApi.etag(base_url: request.base_url),
+          content_type: OpenApi::CONTENT_TYPE
+        )
+      end
+    end
+  end
+end

data/app/controllers/kiosk/server/payment_setup_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # GET <endpoint>/payment_setup/return — the page a payment provider sends
+    # the human's browser back to. `POST <endpoint>/payment_setup` itself is an
+    # ordinary verb, served by {VerbController}.
+    class PaymentSetupController < WireController
+      READY = ['Payment set up', 'Your assistant can now pay on your behalf. You can close this tab.'].freeze
+      UNCONFIRMED = ['Back from payment setup',
+                     'Your assistant will check whether the setup is complete. You can close this tab.'].freeze
+
+      def show
+        PaymentSetup.served!
+        title, text = PaymentSetup.returned(request.query_parameters) ? READY : UNCONFIRMED
+        render body: page(title, text), content_type: 'text/html'
+      end
+
+      private
+
+      def page(title, text)
+        <<~HTML
+          <!DOCTYPE html><html><head><meta charset="utf-8"><title>#{title}</title></head>
+          <body style="font-family:system-ui,sans-serif;text-align:center;padding:64px">
+          <h1>#{title}</h1><p>#{text}</p>
+          </body></html>
+        HTML
+      end
+    end
+  end
+end

data/app/controllers/kiosk/server/verb_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+
+module Kiosk
+  module Server
+    # The verbs the engine itself answers, `POST <endpoint>/payment_setup` and
+    # `POST <endpoint>/request_kyc`, and every verb route that no controller
+    # action can answer: 404 for an unknown name, 405 for a name of the other
+    # kind. An operator's own verb goes straight to the action that declares
+    # it ({Routing::VerbRoute}).
+    #
+    # Gates, in order: identity (401), the verb (404/405), the arguments
+    # (400), the toll (402).
+    class VerbController < WireController
+      # GET <endpoint>/<query-name>
+      def show
+        serve(:query)
+      end
+
+      # POST <endpoint>/<action-name>
+      def create
+        serve(:run)
+      end
+
+      private
+
+      def serve(command)
+        name       = params[:kiosk_verb].to_s
+        identity   = resolve_identity!
+        PaymentSetup.served! if name == PaymentSetup::NAME
+        Kyc.served! if name == Kyc::NAME
+        descriptor = descriptor_for!(command, name)
+        args       = arguments_for(command, name, descriptor)
+
+        execute_wire(command: command, args: args, identity: identity, name: name)
+      end
+
+      # 404 verb_not_found for an unknown name; 405 with `Allow:` for a known
+      # name called with the other kind's method.
+      def descriptor_for!(command, name)
+        registry, other = command == :query ? [Queries, Actions] : [Actions, Queries]
+        return registry.describe(name) if registry.known.include?(name)
+        raise wrong_method(command, name) if other.known.include?(name)
+
+        # Neither: the registry's own 404 names what is registered.
+        registry.describe(name)
+      end
+
+      def wrong_method(command, name)
+        wanted = command == :query ? 'POST' : 'GET'
+        Errors::MethodNotAllowed.new(
+          command == :query ? "#{name.inspect} is an action, not a query" : "#{name.inspect} is a query, not an action",
+          allow: wanted,
+          hint: "call #{wanted} #{Kiosk.configuration.mount_path}/#{name} instead — " \
+                'queries are GET, actions are POST.'
+        )
+      end
+    end
+  end
+end

data/app/controllers/kiosk/server/wire_controller.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+require 'action_dispatch/http/parameters'
+
+module Kiosk
+  module Server
+    # The reserved `GET <endpoint>/schema` (public) and `POST <endpoint>/pay`,
+    # and the base every wire controller inherits its seams from.
+    # Wire response (JSON): success is the handler's payload VERBATIM; an error
+    # is an RFC 9457 problem document.
+    class WireController < ::ActionController::API
+      include VerbWire
+
+      rescue_from Errors::Base, with: :render_wire_error
+
+      # Touching `params` parses the body before any Kiosk code runs.
+      rescue_from ::ActionDispatch::Http::Parameters::ParseError do
+        render_wire_error(Errors.malformed_json(hint: BODY_HINT))
+      end
+
+      # No identity, no toll. A stale `?v=` still gets the current catalog,
+      # with the short TTL.
+      def schema
+        render_public_document(
+          SchemaDocument.json, version: SchemaDocument.digest, etag: SchemaDocument.etag
+        )
+      end
+
+      def pay
+        identity = resolve_identity!
+        body     = parse_body!
+        RequestValidation.validate_body!(body, exchange: 'POST <endpoint>/pay')
+
+        execute_wire(command: :pay, args: body, identity: identity, name: 'pay')
+      end
+
+      private
+
+      def execute_wire(**) = render_result(call_wire(**))
+    end
+  end
+end

data/app/models/kiosk/cart_mandate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kiosk
+  # The signed cart the engine records when it settles a `pay`: the line items
+  # the assistant agreed to pay for. Read-only for the operator.
+  class CartMandate < Server::ApplicationRecord
+    def self.table_name = "#{Kiosk.configuration.schema}.cart_mandates"
+
+    has_many :settlements, class_name: 'Kiosk::Settlement', dependent: nil, inverse_of: :cart_mandate
+
+    # Carts with a line item carrying these attributes, by jsonb containment:
+    # `referencing(order_id: id)` matches `[{"order_id": id, "qty": 2}]`. The
+    # values are quoted by the adapter, never interpolated.
+    scope :referencing, lambda { |**attributes|
+      where(Arel::Nodes::InfixOperation.new(
+              '@>', arel_table[:line_items],
+              Arel::Nodes.build_quoted([attributes.transform_values(&:to_s)].to_json)
+            ))
+    }
+  end
+end

data/app/models/kiosk/server/application_record.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The base of the engine's models.
+    class ApplicationRecord < ::ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/kiosk/settlement.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Kiosk
+  # The receipt the engine writes after a successful `pay` capture.
+  class Settlement < Server::ApplicationRecord
+    include Kiosk::Owned
+
+    def self.table_name = "#{Kiosk.configuration.schema}.settlements"
+
+    belongs_to :cart_mandate, class_name: 'Kiosk::CartMandate', inverse_of: :settlements
+  end
+end

data/app/models/kiosk/visit.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Kiosk
+  # A visit the operator fulfilled: a table honoured, an appointment kept. Its
+  # value counts toward the customer's recent spend, so an operator that takes
+  # no payment can still lower the proof-of-work toll for a returning customer.
+  class Visit < Server::ApplicationRecord
+    def self.table_name = "#{Kiosk.configuration.schema}.visits"
+
+    # Call it when the visit happens, with what the visit was worth.
+    def self.record!(user_id:, value_cents:) = create!(user_id:, value_cents:)
+  end
+end

data/app/views/kiosk/server/assistants/show.html.erb

@@ -0,0 +1,94 @@
+<%# «Link an assistant» page (link flow — Kiosk extension).
+    Minimal on purpose — override by shipping
+    app/views/kiosk/server/assistants/show.html.erb in the host app. %>
+<main>
+  <h1>Linked assistant accounts</h1>
+
+  <% if @notice %><p role="status"><%= @notice %></p><% end %>
+  <% if @error %><p role="alert"><%= @error %></p><% end %>
+
+  <% if @link_code %>
+    <section>
+      <h2>Your link code</h2>
+      <p>
+        Paste this into your assistant's chat. It works once and expires in
+        <%= @expires_in %> seconds — it is shown only now.
+      </p>
+      <p><code><%= @link_code %></code></p>
+    </section>
+  <% end %>
+
+  <section>
+    <h2>Link a new assistant</h2>
+    <p>
+      Mint a code, hand it to your assistant; the assistant redeems it with
+      its own key and is then bound to your account.
+    </p>
+    <form action="<%= @page_path %>/link" method="post">
+      <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+      <button type="submit">Mint a link code</button>
+    </form>
+  </section>
+
+  <section>
+    <h2>Currently linked</h2>
+    <% unless @spending_cap_enforced %>
+      <p role="note">
+        <strong>Note:</strong> this origin configures no <code>spending_cap</code>
+        seam, so a cap saved below is recorded against the assistant but nothing
+        reads it when a charge is settled. To make it bind, set
+        <code>c.spending_cap = Kiosk::Server::ColumnSpendingCap.new</code> in the
+        Kiosk initializer.
+      </p>
+    <% end %>
+    <% if @assistants.empty? %>
+      <p>No assistant accounts are linked yet.</p>
+    <% else %>
+      <ul>
+        <% @assistants.each do |assistant| %>
+          <li>
+            <strong><%= assistant[:human_label].to_s.empty? ? "(unnamed)" : assistant[:human_label] %></strong>
+            <code><%= assistant[:fingerprint] %></code>
+            — linked <%= assistant[:created_at] %>
+            <p>
+              <%
+                spent = assistant[:spent_cents].map { |currency, cents| "#{cents} cents in #{currency.upcase}" }
+              %>
+              spent: <%= spent.empty? ? "0 cents" : spent.join(", ") %> —
+              <%
+                cap = assistant[:spending_cap_cents]
+                cap_label = if cap.nil?
+                              "cap: none"
+                            elsif cap.zero?
+                              "cap: disabled"
+                            else
+                              "cap: #{cap} cents in #{assistant[:spending_cap_currency].upcase}"
+                            end
+              %>
+              <%= cap_label %>
+            </p>
+            <form action="<%= @page_path %>/update" method="post">
+              <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+              <input type="hidden" name="agent_id" value="<%= assistant[:agent_id] %>">
+              <label>Label
+                <input type="text" name="human_label" value="<%= assistant[:human_label] %>">
+              </label>
+              <label>Spending cap (cents, blank = no cap)
+                <input type="number" name="spending_cap_cents" min="0" value="<%= assistant[:spending_cap_cents] %>">
+              </label>
+              <label>Cap currency (ISO 4217 code; the assistant cannot pay in another currency)
+                <input type="text" name="spending_cap_currency" maxlength="3" value="<%= assistant[:spending_cap_currency]&.upcase %>">
+              </label>
+              <button type="submit">Save</button>
+            </form>
+            <form action="<%= @page_path %>/unlink" method="post">
+              <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+              <input type="hidden" name="agent_id" value="<%= assistant[:agent_id] %>">
+              <button type="submit">Unlink</button>
+            </form>
+          </li>
+        <% end %>
+      </ul>
+    <% end %>
+  </section>
+</main>

data/app/views/kiosk/server/device_verify/decided.html.erb

@@ -0,0 +1,14 @@
+<%# Claim-ceremony decision confirmation. Override by shipping
+    app/views/kiosk/server/device_verify/decided.html.erb in the host app. %>
+<main>
+  <% if @decision == :approved %>
+    <h1>Approved</h1>
+    <p>
+      The assistant is now cleared to link to your account — you can return
+      to it. You can unlink it at any time from your linked-assistants page.
+    </p>
+  <% else %>
+    <h1>Denied</h1>
+    <p>The request was denied. Nothing was linked to your account.</p>
+  <% end %>
+</main>

data/app/views/kiosk/server/device_verify/show.html.erb

@@ -0,0 +1,53 @@
+<%# Claim-ceremony verify page. Minimal on purpose — override
+    by shipping app/views/kiosk/server/device_verify/show.html.erb in the
+    host app. %>
+<main>
+  <h1>Link an assistant to your account</h1>
+
+  <% if @error %>
+    <p role="alert"><%= @error %></p>
+  <% end %>
+
+  <% if @authorization %>
+    <p>
+      An assistant is asking to be linked to <strong>your</strong> account.
+      Approve only if you started this yourself and the fingerprint below
+      matches the one your assistant shows you.
+    </p>
+    <%# The access line is a CONSENT field, not decoration. What the
+        assistant ends up able to do is decided by the role stamped here, off
+        the signed-in human's own identity — so the human approving the link
+        is shown the same value the token will carry. It is not something the
+        assistant asked for; the request that opened this ceremony is
+        unauthenticated and refuses to carry a role at all. %>
+    <dl>
+      <dt>Key fingerprint</dt>
+      <dd><code><%= @fingerprint %></code></dd>
+      <dt>Requested at</dt>
+      <dd><%= @authorization.created_at.utc %></dd>
+      <dt>Access you are handing it</dt>
+      <dd>
+        <% if @role %>
+          It will act as you, with your own <code><%= @role %></code> access at
+          this site — the assistant does not get to ask for any other.
+        <% else %>
+          It will act as you. This site gives your account no separate access
+          level, so the assistant gets the same access you have.
+        <% end %>
+      </dd>
+    </dl>
+    <form action="<%= request.path %>" method="post">
+      <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+      <input type="hidden" name="user_code" value="<%= @user_code %>">
+      <button type="submit" name="decision" value="approve">Approve</button>
+      <button type="submit" name="decision" value="deny">Deny</button>
+    </form>
+  <% else %>
+    <p>Enter the code your assistant shows you (looks like <code>WDJB-MJHT</code>).</p>
+    <form action="<%= request.path %>" method="get">
+      <label for="user_code">Code</label>
+      <input type="text" id="user_code" name="user_code" autocomplete="off" autofocus>
+      <button type="submit">Continue</button>
+    </form>
+  <% end %>
+</main>

data/lib/generators/kiosk/install/install_generator.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/base'
+require 'rails/generators/migration'
+
+module Kiosk
+  module Generators
+    # `bin/rails g kiosk:install`: writes the Kiosk initializer, the wire routes
+    # and the migrations, with the DDL of {Kiosk::Server::SchemaDefinitions} written into each.
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Generate the Kiosk initializer and its canonical base migrations. ' \
+           'Draws the engine mount, so the origin answers on the wire.'
+
+      class_option :user_table,    type: :string, default: 'users',
+                                   desc: "Provider's user table name"
+      class_option :user_id_type,  type: :string, default: 'uuid',
+                                   desc: 'User-id column type: uuid | bigint | integer | text'
+      class_option :schema,        type: :string, default: 'kiosk',
+                                   desc: 'Postgres schema name for Kiosk helpers and tables'
+      class_option :guc_namespace, type: :string, default: 'app',
+                                   desc: 'GUC namespace prefix used in the session GUC names'
+
+      # Ascending timestamps within one run, so the migrations sort in order.
+      @migration_counter = 0
+      class << self
+        def next_migration_number(_dirname)
+          @migration_counter ||= 0
+          number = Time.now.utc.strftime('%Y%m%d%H%M%S').to_i + @migration_counter
+          @migration_counter += 1
+          format('%014d', number)
+        end
+      end
+
+      no_commands do
+        # One SchemaDefinitions method's DDL, indented for the migration's heredoc.
+        def ddl(name, **)
+          Kiosk::Server::SchemaDefinitions.public_send(:"#{name}_sql", schema: options[:schema], **)
+                                          .gsub(/^(?=.)/, '      ')
+        end
+
+        def user_id_type = options[:user_id_type].to_sym
+      end
+
+      def create_initializer
+        template 'initializer.rb.tt', 'config/initializers/kiosk.rb'
+      end
+
+      # schema.rb dumps only the search path's schemas unless told otherwise;
+      # public goes first because the kiosk tables reference the user table.
+      def dump_kiosk_schema
+        application %(config.active_record.dump_schemas = "public,#{options[:schema]}")
+      end
+
+      # The engine mount, and a place for the operator's verbs under it.
+      def draw_wire_routes
+        route <<~RUBY
+          kiosk do
+            # queries :catalog
+            # actions :place_order
+          end
+        RUBY
+      end
+
+      def create_schema_migration
+        migration_template 'create_kiosk_schema.rb.tt',
+                           'db/migrate/create_kiosk_schema.rb'
+      end
+
+      def create_identity_tables_migration
+        migration_template 'create_kiosk_identity_tables.rb.tt',
+                           'db/migrate/create_kiosk_identity_tables.rb'
+      end
+
+      def create_device_authorizations_migration
+        migration_template 'create_kiosk_device_authorizations.rb.tt',
+                           'db/migrate/create_kiosk_device_authorizations.rb'
+      end
+
+      def create_mandates_migration
+        migration_template 'create_kiosk_mandates.rb.tt',
+                           'db/migrate/create_kiosk_mandates.rb'
+      end
+
+      def create_kyc_attributes_migration
+        migration_template 'create_kiosk_kyc_attributes.rb.tt',
+                           'db/migrate/create_kiosk_kyc_attributes.rb'
+      end
+
+      def create_events_migration
+        migration_template 'create_kiosk_events.rb.tt',
+                           'db/migrate/create_kiosk_events.rb'
+      end
+
+      def create_pow_spent_migration
+        migration_template 'create_kiosk_pow_spent.rb.tt',
+                           'db/migrate/create_kiosk_pow_spent.rb'
+      end
+
+      def create_revocations_migration
+        migration_template 'create_kiosk_revocations.rb.tt',
+                           'db/migrate/create_kiosk_revocations.rb'
+      end
+
+      def create_auth_challenges_migration
+        migration_template 'create_kiosk_auth_challenges.rb.tt',
+                           'db/migrate/create_kiosk_auth_challenges.rb'
+      end
+
+      def create_visits_migration
+        migration_template 'create_kiosk_visits.rb.tt',
+                           'db/migrate/create_kiosk_visits.rb'
+      end
+
+      def create_refunds_migration
+        migration_template 'create_kiosk_refunds.rb.tt',
+                           'db/migrate/create_kiosk_refunds.rb'
+      end
+    end
+  end
+end