kiosk-server 0.6.1 → 0.6.28

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiosk-server
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.28
 platform: ruby
 authors:
 - Phil Pirozhkov
@@ -164,7 +164,7 @@ dependencies:
 description: |
   kiosk-server is the host-side surface for Kiosk. The full surface ships:
 
-    - The controllers — the per-verb wire (GET <endpoint>/<query-name>,
+    - The controllers — the per-verb endpoints (GET <endpoint>/<query-name>,
       POST <endpoint>/<action-name>) and the reserved endpoints
       (/kiosk/schema, /kiosk/pay), a derived OpenAPI description of both,
       OAuth client registration (RFC 7591) and the token endpoint
@@ -176,7 +176,7 @@ description: |
     - Kiosk::Server::Executor — dispatches a resolved command to the
       queries and actions the host registered.
     - Client registration and authentication, with a pluggable agent-IdP.
-    - The PoW gate that enforces a kiosk-reputation policy's challenge
+    - The proof-of-work toll that a kiosk-reputation policy sets
       (soft dependency; zero overhead when no policy is set).
     - A Rack middleware injecting the Kiosk-Server-Version /
       Kiosk-API-Version / Kiosk-Min-Client response headers, a pure-Ruby
@@ -186,7 +186,7 @@ description: |
 
   The Rails engine serves that whole surface from one `kiosk` block in
   config/routes.rb, which mounts it at Kiosk.configuration.mount_path —
-  drawing the wire/auth/JWKS/KYC/binding routes under the mount and
+  drawing the verb/auth/JWKS/KYC/binding routes under the mount and
   installing the root-relative discovery routes (agents.txt, .well-known)
   into the host — then one route per query and action the block names. It
   also auto-injects the headers middleware.
@@ -222,6 +222,7 @@ files:
 - app/views/kiosk/server/assistants/show.html.erb
 - app/views/kiosk/server/device_verify/decided.html.erb
 - app/views/kiosk/server/device_verify/show.html.erb
+- app/views/layouts/kiosk/server/application.html.erb
 - lib/generators/kiosk/install/install_generator.rb
 - lib/generators/kiosk/install/templates/create_kiosk_device_authorizations.rb.tt
 - lib/generators/kiosk/install/templates/create_kiosk_events.rb.tt
@@ -231,7 +232,6 @@ files:
 - lib/generators/kiosk/install/templates/create_kiosk_pow_spent.rb.tt
 - lib/generators/kiosk/install/templates/create_kiosk_refunds.rb.tt
 - lib/generators/kiosk/install/templates/create_kiosk_revocations.rb.tt
-- lib/generators/kiosk/install/templates/create_kiosk_schema.rb.tt
 - lib/generators/kiosk/install/templates/create_kiosk_visits.rb.tt
 - lib/generators/kiosk/install/templates/initializer.rb.tt
 - lib/kiosk/handler.rb
@@ -245,6 +245,7 @@ files:
 - lib/kiosk/server/agent_identity_providers/default_agent_idp.rb
 - lib/kiosk/server/agent_rotation.rb
 - lib/kiosk/server/argument_decoder.rb
+- lib/kiosk/server/assistant_accounts.rb
 - lib/kiosk/server/assistant_key.rb
 - lib/kiosk/server/audit_sink.rb
 - lib/kiosk/server/auth_toll.rb
@@ -271,6 +272,7 @@ files:
 - lib/kiosk/server/events.rb
 - lib/kiosk/server/events_cable.rb
 - lib/kiosk/server/events_connection.rb
+- lib/kiosk/server/events_replay.rb
 - lib/kiosk/server/executor.rb
 - lib/kiosk/server/executor/repeat.rb
 - lib/kiosk/server/executor/spending_cap.rb
@@ -290,6 +292,7 @@ files:
 - lib/kiosk/server/link_code.rb
 - lib/kiosk/server/linked_assistants.rb
 - lib/kiosk/server/mandate_verifier.rb
+- lib/kiosk/server/money.rb
 - lib/kiosk/server/oauth_answers.rb
 - lib/kiosk/server/oauth_error.rb
 - lib/kiosk/server/open_api.rb
@@ -307,7 +310,6 @@ files:
 - lib/kiosk/server/result.rb
 - lib/kiosk/server/revocation_stores.rb
 - lib/kiosk/server/routing.rb
-- lib/kiosk/server/schema_definitions.rb
 - lib/kiosk/server/schema_document.rb
 - lib/kiosk/server/schema_slots.rb
 - lib/kiosk/server/schemas/auth.schema.json
@@ -317,15 +319,14 @@ files:
 - lib/kiosk/server/schemas/pow.schema.json
 - lib/kiosk/server/sd_jwt.rb
 - lib/kiosk/server/session_context.rb
-- lib/kiosk/server/settled_spend.rb
 - lib/kiosk/server/signing_key.rb
+- lib/kiosk/server/tolled_calls.rb
 - lib/kiosk/server/verb_registry.rb
 - lib/kiosk/server/verb_vocabulary.rb
 - lib/kiosk/server/verb_wire.rb
 - lib/kiosk/server/version.rb
 - lib/kiosk/server/well_known.rb
 - lib/kiosk/server/wire_rendering.rb
-- lib/kiosk/server/wrong_door.rb
 - lib/kiosk/skill_link.rb
 - listen.py
 - requirements.txt

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

@@ -1,17 +0,0 @@
-# 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/kiosk/server/schema_definitions.rb

@@ -1,320 +0,0 @@
-# frozen_string_literal: true
-
-module Kiosk
-  module Server
-    # The SQL of the migrations `kiosk:install` emits, one method per
-    # migration, each creating its tables in their final shape. No database
-    # connection; the host's migrations `execute` it.
-    # rubocop:disable-next Metrics/ModuleLength, Metrics/MethodLength -- each method returns one migration's DDL as one SQL heredoc
-    module SchemaDefinitions
-      module_function
-
-      # 001: the schema and the `current_*()` GUC readers.
-      def helper_functions_sql(schema: nil, guc_namespace: nil, user_id_type: nil)
-        schema ||= Kiosk.configuration.schema
-        guc_namespace ||= Kiosk.configuration.guc_namespace
-        user_id_type  ||= Kiosk.configuration.user_id_type
-        cast = user_id_cast(user_id_type)
-
-        <<~DDL.strip
-          CREATE SCHEMA IF NOT EXISTS "#{schema}";
-
-          CREATE OR REPLACE FUNCTION "#{schema}".current_user_id() RETURNS #{cast} LANGUAGE sql STABLE AS $$
-            SELECT NULLIF(current_setting('#{guc_namespace}.current_user_id', true), '')::#{cast}
-          $$;
-
-          CREATE OR REPLACE FUNCTION "#{schema}".current_role() RETURNS text LANGUAGE sql STABLE AS $$
-            SELECT NULLIF(current_setting('#{guc_namespace}.current_role', true), '')
-          $$;
-
-          CREATE OR REPLACE FUNCTION "#{schema}".current_actor() RETURNS text LANGUAGE sql STABLE AS $$
-            SELECT NULLIF(current_setting('#{guc_namespace}.current_actor', true), '')
-          $$;
-
-          CREATE OR REPLACE FUNCTION "#{schema}".current_agent_id() RETURNS uuid LANGUAGE sql STABLE AS $$
-            SELECT NULLIF(current_setting('#{guc_namespace}.current_agent_id', true), '')::uuid
-          $$;
-        DDL
-      end
-
-      # 002: `agents` (`spending_cap_cents`: NULL unlimited, 0 disabled; a cap
-      # has its `spending_cap_currency`), `agent_tokens`, `agent_mappings`.
-      def identity_tables_sql(schema: nil, user_id_type: nil, user_table: 'users')
-        schema ||= Kiosk.configuration.schema
-        user_id_type ||= Kiosk.configuration.user_id_type
-        col_type = user_id_cast(user_id_type)
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".agents (
-            id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            user_id             #{col_type} NOT NULL REFERENCES "#{user_table}"(id) ON DELETE CASCADE,
-            allowed_roles       text[] NOT NULL DEFAULT '{}'::text[],
-            public_key          text,
-            human_label         text,
-            spending_cap_cents  bigint,
-            spending_cap_currency text CHECK (spending_cap_currency ~ '^[a-z]{3}$'),
-            created_at          timestamptz NOT NULL DEFAULT now(),
-            revoked_at          timestamptz,
-            issuer              text NOT NULL,
-            CONSTRAINT agents_spending_cap_currency_set
-              CHECK ((spending_cap_cents IS NULL) = (spending_cap_currency IS NULL))
-          );
-
-          CREATE INDEX IF NOT EXISTS idx_agents_user_id ON "#{schema}".agents (user_id) WHERE revoked_at IS NULL;
-          -- Dedupe at the DB, not via SELECT-then-INSERT (TOCTOU): two LIVE
-          -- rows for one public key on one origin cannot coexist. Partial
-          -- (WHERE revoked_at IS NULL) so a revoked key can re-register.
-          CREATE UNIQUE INDEX IF NOT EXISTS idx_agents_issuer_public_key_live
-            ON "#{schema}".agents (issuer, public_key) WHERE revoked_at IS NULL;
-
-          CREATE TABLE IF NOT EXISTS "#{schema}".agent_tokens (
-            id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            agent_id    uuid NOT NULL REFERENCES "#{schema}".agents(id) ON DELETE CASCADE,
-            token_hash  text NOT NULL,
-            issued_at   timestamptz NOT NULL DEFAULT now(),
-            expires_at  timestamptz NOT NULL,
-            revoked_at  timestamptz
-          );
-          CREATE INDEX IF NOT EXISTS idx_agent_tokens_agent_id ON "#{schema}".agent_tokens (agent_id);
-          CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_tokens_hash ON "#{schema}".agent_tokens (token_hash);
-
-          CREATE TABLE IF NOT EXISTS "#{schema}".agent_mappings (
-            provider     text NOT NULL,
-            external_id  text NOT NULL,
-            agent_id     uuid NOT NULL REFERENCES "#{schema}".agents(id) ON DELETE CASCADE,
-            PRIMARY KEY (provider, external_id)
-          );
-        DDL
-      end
-
-      # 004: account-binding requests; codes are stored hashed only.
-      # `requested_role` is the approving human's role, never a client's.
-      def device_authorizations_sql(schema: nil, user_id_type: nil)
-        schema ||= Kiosk.configuration.schema
-        user_id_type ||= Kiosk.configuration.user_id_type
-        col_type = user_id_cast(user_id_type)
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".device_authorizations (
-            id               uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            device_code_hash text NOT NULL,
-            user_code_hash   text NOT NULL,
-            public_key_pem   text,
-            kind             text NOT NULL DEFAULT 'claim',
-            client_id        text NOT NULL,
-            requested_role   text,
-            status           text NOT NULL,
-            user_id          #{col_type},
-            expires_at       timestamptz NOT NULL,
-            consumed_at      timestamptz,
-            created_at       timestamptz NOT NULL DEFAULT now(),
-            CONSTRAINT device_authorizations_status_check
-              CHECK (status IN ('pending', 'approved', 'denied', 'consumed', 'expired')),
-            CONSTRAINT device_authorizations_kind_check
-              CHECK (kind IN ('claim', 'link'))
-          );
-          CREATE UNIQUE INDEX IF NOT EXISTS idx_device_authorizations_code_hash
-            ON "#{schema}".device_authorizations (device_code_hash);
-          -- Only `pending` rows need a unique user_code; approved/consumed
-          -- rows may share codes from past flows without collision.
-          CREATE UNIQUE INDEX IF NOT EXISTS idx_device_authorizations_user_code_pending
-            ON "#{schema}".device_authorizations (user_code_hash)
-            WHERE status = 'pending';
-          CREATE INDEX IF NOT EXISTS idx_device_authorizations_expiry
-            ON "#{schema}".device_authorizations (expires_at)
-            WHERE status IN ('pending', 'approved');
-        DDL
-      end
-
-      # 005: the AP2 trail. `id` is server-generated; `reference` is the hash of
-      # the presented SD-JWT, unique per principal. One checkout holds one live
-      # checkout mandate: `declined_at` records a charge refused with no money
-      # moved, and frees the checkout. A settlement is server-minted.
-      def mandates_sql(schema: nil, user_id_type: nil)
-        schema       ||= Kiosk.configuration.schema
-        user_id_type ||= Kiosk.configuration.user_id_type
-        col_type = user_id_cast(user_id_type)
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".checkout_mandates (
-            id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            reference          text NOT NULL,
-            checkout_hash      text NOT NULL,
-            user_id            #{col_type} NOT NULL,
-            agent_id           uuid NOT NULL,
-            issuer             text NOT NULL,
-            line_items         jsonb NOT NULL,
-            total_amount_cents bigint NOT NULL,
-            currency           text NOT NULL,
-            expires_at         timestamptz NOT NULL,
-            created_at         timestamptz NOT NULL DEFAULT now(),
-            sd_jwt             text NOT NULL,
-            declined_at        timestamptz,
-            UNIQUE (user_id, reference)
-          );
-          CREATE INDEX IF NOT EXISTS idx_checkout_mandates_user_id ON "#{schema}".checkout_mandates (user_id);
-          CREATE UNIQUE INDEX IF NOT EXISTS idx_checkout_mandates_live_checkout
-            ON "#{schema}".checkout_mandates (user_id, checkout_hash) WHERE declined_at IS NULL;
-
-          CREATE TABLE IF NOT EXISTS "#{schema}".payment_mandates (
-            id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            reference           text NOT NULL,
-            checkout_mandate_id uuid NOT NULL REFERENCES "#{schema}".checkout_mandates(id) ON DELETE CASCADE,
-            user_id             #{col_type} NOT NULL,
-            agent_id            uuid NOT NULL,
-            issuer              text NOT NULL,
-            payment_instrument  text NOT NULL,
-            amount_cents        bigint NOT NULL,
-            currency            text NOT NULL,
-            expires_at          timestamptz,
-            created_at          timestamptz NOT NULL DEFAULT now(),
-            sd_jwt              text NOT NULL,
-            UNIQUE (user_id, reference)
-          );
-          CREATE INDEX IF NOT EXISTS idx_payment_mandates_user_id  ON "#{schema}".payment_mandates (user_id);
-          CREATE INDEX IF NOT EXISTS idx_payment_mandates_checkout ON "#{schema}".payment_mandates (checkout_mandate_id);
-
-          CREATE TABLE IF NOT EXISTS "#{schema}".settlements (
-            id                   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            checkout_mandate_id  uuid NOT NULL REFERENCES "#{schema}".checkout_mandates(id) ON DELETE CASCADE,
-            user_id              #{col_type} NOT NULL,
-            agent_id             uuid NOT NULL,
-            issuer               text NOT NULL,
-            psp_reference        text NOT NULL,
-            settled_amount_cents bigint NOT NULL,
-            currency             text NOT NULL,
-            network_confirmation_id text,
-            settled_at           timestamptz NOT NULL,
-            UNIQUE (checkout_mandate_id)
-          );
-          CREATE INDEX IF NOT EXISTS idx_settlements_user_id  ON "#{schema}".settlements (user_id);
-          CREATE INDEX IF NOT EXISTS idx_settlements_checkout ON "#{schema}".settlements (checkout_mandate_id);
-        DDL
-      end
-
-      # 006: KYC grants and open verifications, keyed on the person.
-      def kyc_attributes_sql(schema: nil, user_id_type: nil, user_table: nil)
-        schema       ||= Kiosk.configuration.schema
-        user_id_type ||= Kiosk.configuration.user_id_type
-        user_table   ||= configured_user_table
-        col_type = user_id_cast(user_id_type)
-        person   = %(#{col_type} NOT NULL REFERENCES "#{user_table}"(id) ON DELETE CASCADE)
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".kyc_attributes (
-            user_id    #{person},
-            name       text NOT NULL,
-            granted_at timestamptz NOT NULL DEFAULT now(),
-            PRIMARY KEY (user_id, name)
-          );
-
-          CREATE TABLE IF NOT EXISTS "#{schema}".kyc_requests (
-            id          text PRIMARY KEY,
-            user_id     #{person},
-            nonce       text NOT NULL,
-            approved_at timestamptz,
-            created_at  timestamptz NOT NULL DEFAULT now()
-          );
-          CREATE INDEX IF NOT EXISTS idx_kyc_requests_user_id ON "#{schema}".kyc_requests (user_id, created_at);
-        DDL
-      end
-
-      # 007: the event tail; `id` is the origin's one monotonic cursor.
-      def events_sql(schema: nil)
-        schema ||= Kiosk.configuration.schema
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".events (
-            id           bigserial   PRIMARY KEY,
-            identity_key text        NOT NULL,
-            topic        text        NOT NULL,
-            subject      text,
-            occurred_at  timestamptz NOT NULL,
-            data         jsonb       NOT NULL,
-            created_at   timestamptz NOT NULL DEFAULT now()
-          );
-          -- `since` for one subscriber: the cursor scan, in id order.
-          CREATE INDEX IF NOT EXISTS idx_events_identity_key_id
-            ON "#{schema}".events (identity_key, id);
-          -- The retention sweep only.
-          CREATE INDEX IF NOT EXISTS idx_events_created_at
-            ON "#{schema}".events (created_at);
-        DDL
-      end
-
-      # 008: spent ids of proof-of-work challenges and client assertions; the primary key is the single-use gate.
-      def pow_spent_sql(schema: nil)
-        schema ||= Kiosk.configuration.schema
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".pow_spent (
-            id         text        PRIMARY KEY,
-            expires_at timestamptz NOT NULL
-          );
-          -- Supports the TTL sweep only; the PK above is what enforces
-          -- single-use.
-          CREATE INDEX IF NOT EXISTS idx_pow_spent_expires_at
-            ON "#{schema}".pow_spent (expires_at);
-        DDL
-      end
-
-      # 009: each agent's revocation watermark: a token issued before it stops verifying.
-      def revocations_sql(schema: nil)
-        schema ||= Kiosk.configuration.schema
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".revocations (
-            agent_id       uuid        PRIMARY KEY REFERENCES "#{schema}".agents(id) ON DELETE CASCADE,
-            revoked_before timestamptz NOT NULL
-          );
-        DDL
-      end
-
-      # 011: the visits an operator records as fulfilled; reputation counts their value.
-      def visits_sql(schema: nil, user_id_type: nil)
-        schema ||= Kiosk.configuration.schema
-        col_type = user_id_cast(user_id_type || Kiosk.configuration.user_id_type)
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".visits (
-            id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            user_id     #{col_type} NOT NULL,
-            value_cents bigint NOT NULL CHECK (value_cents >= 0),
-            visited_at  timestamptz NOT NULL DEFAULT now()
-          );
-          CREATE INDEX IF NOT EXISTS idx_visits_user_id ON "#{schema}".visits (user_id, visited_at);
-        DDL
-      end
-
-      # 012: the refunds of settled charges, one row per PSP refund; recent
-      # spend counts a settlement less what was refunded of it.
-      def refunds_sql(schema: nil)
-        schema ||= Kiosk.configuration.schema
-
-        <<~DDL.strip
-          CREATE TABLE IF NOT EXISTS "#{schema}".refunds (
-            id                    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-            settlement_id         uuid NOT NULL REFERENCES "#{schema}".settlements(id) ON DELETE CASCADE,
-            psp_reference         text NOT NULL UNIQUE,
-            refunded_amount_cents bigint NOT NULL CHECK (refunded_amount_cents > 0),
-            refunded_at           timestamptz NOT NULL
-          );
-          CREATE INDEX IF NOT EXISTS idx_refunds_settlement_id ON "#{schema}".refunds (settlement_id);
-        DDL
-      end
-
-      def configured_user_table = Kiosk.configuration.user_model.to_s.constantize.table_name
-
-      def user_id_cast(user_id_type)
-        case user_id_type.to_sym
-        when :uuid               then 'uuid'
-        when :bigint, :integer   then user_id_type.to_s
-        when :text               then 'text'
-        else
-          raise ArgumentError,
-                "user_id_type must be one of :uuid, :bigint, :integer, :text — got #{user_id_type.inspect}"
-        end
-      end
-    end
-  end
-end

data/lib/kiosk/server/settled_spend.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Kiosk
-  module Server
-    # What an assistant spent: each settlement less what was refunded of it,
-    # never below zero, one tally per currency. The «Link an assistant» page
-    # shows this figure. The spending cap counts it plus the carts in flight.
-    module SettledSpend
-      module_function
-
-      # The net cents of the current `settlements` row.
-      def net_cents_sql(schema)
-        <<~SQL.squish
-          GREATEST(settlements.settled_amount_cents - (
-            SELECT COALESCE(SUM(r.refunded_amount_cents), 0) FROM #{schema}.refunds r WHERE r.settlement_id = settlements.id
-          ), 0)
-        SQL
-      end
-    end
-  end
-end

data/lib/kiosk/server/wrong_door.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require 'active_support/concern'
-
-module Kiosk
-  module Server
-    # The account holder's browser pages. A JSON caller without a CSRF token is
-    # an assistant at the wrong door: the answer points it at the wire. Browser
-    # requests re-raise untouched. Each page's controller sets WRONG_DOOR_MESSAGE.
-    module WrongDoor
-      extend ActiveSupport::Concern
-
-      included do
-        rescue_from ::ActionController::InvalidAuthenticityToken do |error|
-          raise error unless json_request?
-
-          render json: wrong_door_envelope, status: :unprocessable_entity
-        end
-      end
-
-      private
-
-      # An explicit JSON Accept or a JSON body; anything ambiguous counts as a browser.
-      def json_request?
-        return true if request.format.json?
-
-        !!request.content_mime_type&.json?
-      rescue StandardError
-        false
-      end
-
-      # Not a wire problem document or wire error code: this page is not the wire.
-      def wrong_door_envelope
-        hint = "assistants use the wire: GET #{request.base_url}/.well-known/kiosk.json " \
-               'for the register/login endpoints, then GET <endpoint>/schema ' \
-               '(public) for the verbs this origin serves'
-        { ok: false,
-          error: { code: 'invalid_authenticity_token', message: self.class::WRONG_DOOR_MESSAGE, hint: hint } }
-      end
-    end
-  end
-end