kiosk-core 0.6.1 → 0.6.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ae058e2f502098d86eaaf73f923777a3a26c15a5a7e639aadf9603fc0127b99
-  data.tar.gz: cd5fa11750a7ee2e47a2392132981f964c7524fbe2b570dea326485785af043b
+  metadata.gz: 771cd195ba7e72ae0996466be7c0cab4eb3b1fa35ebfd4506b0d13eb7bb0ce08
+  data.tar.gz: bcf91d7119b9bfe67458d4e250da00ba55ccd5e59310c2431be04025faa20221
 SHA512:
-  metadata.gz: 4f37b026e62693cbc19c2cdb863d10b1f9a900d7506490bfe7386fb258d645875d59c0506eaeb8970f2f71d81f7aecae88d9058779839120cfb6039e306dfc83
-  data.tar.gz: 40ef0e8d8ae11bd56428d5c49bd7a39ae5042270469c323eedf1ed32cf7319db338108f3c1155a803addea92745cf326038df44fbf6493f0f76beee9ebb23fc9
+  metadata.gz: 0aa408791a5e60ce07a1916084e20635773537a534bef508c5627432dfe13400ee46b52e4a74552684d2f4beddd5615259d9ff32ad0f536c76d362d746cb5c63
+  data.tar.gz: 4a12f9d851edd714c8b4e3680119456184565d953dfd1c5a11d81b75d321369e730279beba287a8f339be0d18482eb3b3ddcd5b204d4aa6bcdcd840e7cfc7f4d

data/CHANGELOG.md

@@ -12,6 +12,116 @@ already written is edited.
 
 ## [Unreleased]
 
+## [0.6.28] — 2026-10-26
+
+- 2026-10-26: Version 0.6.28, the tree cut that matches skill 0.6.28.
+
+## [0.6.27] — 2026-10-26
+
+- 2026-10-26: Version 0.6.27, the tree cut that matches skill 0.6.27.
+## [0.6.26] — 2026-10-26
+
+- 2026-10-26: Version 0.6.26, the tree cut that matches skill 0.6.26.
+## [0.6.25] — 2026-10-26
+
+- 2026-10-26: Version 0.6.25, the tree cut that matches skill 0.6.25.
+- 2026-10-26: The README names the mandate types the gem defines: `Kiosk::Mandate::CheckoutMandate` and `Kiosk::Mandate::PaymentMandate`.
+
+## [0.6.24] — 2026-10-26
+
+- 2026-10-26: Version 0.6.24, the tree cut that matches skill 0.6.24.
+
+## [0.6.23] — 2026-10-26
+
+- 2026-10-26: Version 0.6.23, the tree cut that matches skill 0.6.23.
+
+## [0.6.22] — 2026-10-26
+
+- 2026-10-26: Version 0.6.22, the tree cut that matches skill 0.6.22.
+
+## [0.6.21] — 2026-10-26
+
+- 2026-10-26: Version 0.6.21, the tree cut that matches skill 0.6.21.
+
+## [0.6.20] — 2026-10-26
+
+- 2026-10-26: Version 0.6.20, the tree cut that matches skill 0.6.20.
+
+## [0.6.19] — 2026-10-26
+
+- 2026-10-26: Version 0.6.19, the tree cut that matches skill 0.6.19.
+
+## [0.6.18] — 2026-10-25
+
+- 2026-10-25: Version 0.6.18, the tree cut that matches skill 0.6.18.
+
+## [0.6.17] — 2026-10-25
+
+- 2026-10-25: Version 0.6.17, the tree cut that matches skill 0.6.17.
+
+## [0.6.16] — 2026-10-25
+
+- 2026-10-25: Version 0.6.16, the tree cut that matches skill 0.6.16.
+- 2026-10-25: `Kiosk::Identity` takes the actor `agent` or `human`; `service` is removed.
+
+## [0.6.15] — 2026-10-25
+
+- 2026-10-25: Version 0.6.15, the tree cut that matches skill 0.6.15.
+
+## [0.6.14] — 2026-10-25
+
+- 2026-10-25: Version 0.6.14, the tree cut that matches skill 0.6.14.
+
+## [0.6.13] — 2026-10-25
+
+- 2026-10-25: Version 0.6.13, the tree cut that matches skill 0.6.13.
+
+## [0.6.12] — 2026-10-24
+
+- 2026-10-24: Version 0.6.12, the tree cut that matches skill 0.6.12.
+
+- 2026-10-24: `KycProviders::Base.new(issuer:, public_key:, audience:)` names what an attestation is checked against; `open_verification` takes no `audience:`.
+
+## [0.6.11] — 2026-10-24
+
+- 2026-10-24: Version 0.6.11, the tree cut that matches skill 0.6.11.
+
+## [0.6.10] — 2026-10-23
+
+- 2026-10-23: Version 0.6.10, the tree cut that matches skill 0.6.10.
+
+## [0.6.9] — 2026-10-23
+
+- 2026-10-23: Version 0.6.9, the tree cut that matches skill 0.6.9.
+
+## [0.6.8] — 2026-10-22
+
+- 2026-10-22: Version 0.6.8, the tree cut that matches skill 0.6.8.
+
+## [0.6.7] — 2026-10-22
+
+- 2026-10-22: Version 0.6.7, the tree cut that matches skill 0.6.7.
+
+## [0.6.6] — 2026-10-22
+
+- 2026-10-22: Version 0.6.6, the tree cut that matches skill 0.6.6.
+
+## [0.6.5] — 2026-10-22
+
+- 2026-10-22: Version 0.6.5, the tree cut that matches skill 0.6.5.
+
+## [0.6.4] — 2026-10-22
+
+- 2026-10-22: Version 0.6.4, the tree cut that matches skill 0.6.4.
+
+## [0.6.3] — 2026-10-22
+
+- 2026-10-22: Version 0.6.3, the tree cut that matches skill 0.6.3.
+
+## [0.6.2] — 2026-10-22
+
+- 2026-10-22: Version 0.6.2, the tree cut that matches skill 0.6.2.
+
 ## [0.6.1] — 2026-10-22
 
 - 2026-10-22: Version 0.6.1, the tree cut that matches skill 0.6.1.

data/README.md

@@ -4,13 +4,13 @@ Core abstractions for the [Kiosk](https://kiosk.tech) framework.
 
 ## What is Kiosk
 
-Kiosk is the standards-based open protocol that lets your customers' AI assistants discover, transact with, and pay your service. Its Ruby reference implementation is a Rails engine: REST endpoint, multi-assistant identity per user, app-layer-authorized data plane with opt-in Postgres RLS defense-in-depth, AP2 mandate trail. Alpha. Apache-2.0.
+Kiosk is the standards-based open protocol that lets the AI assistants of visitors and customers discover, transact with, and pay an operator's service. Its Ruby reference implementation is a Rails engine: one HTTP API, several assistants on one customer account, app-layer-authorized data plane with opt-in Postgres RLS defense-in-depth, AP2 mandate trail. Alpha. Apache-2.0.
 
 ## What is kiosk-core
 
 The foundation. Defines:
 
-- **Value types** — `Kiosk::Identity`, `Kiosk::Mandate` (intent / cart / payment)
+- **Value types** — `Kiosk::Identity`, `Kiosk::Mandate::CheckoutMandate` and `Kiosk::Mandate::PaymentMandate` (the AP2 checkout and payment mandates)
 - **Abstract base classes** that adapter gems extend:
   - `Kiosk::AgentIdentityProviders::Base`
   - `Kiosk::UserIdentityProviders::Base`
@@ -18,13 +18,13 @@ The foundation. Defines:
   - `Kiosk::KycProviders::Base`
 
   An agent-IdP adapter's `agent_id` **must be a UUID string**: `Identity`
-  checks only that it is present, but every `agent_id` column in the canonical
-  Postgres schema and the `kiosk.current_agent_id()` helper are typed `uuid`,
+  checks only that it is present, but every `agent_id` column of the Kiosk tables
+  (and kiosk-rls's `kiosk_current_agent_id()`) is typed `uuid`,
   and there is no `user_id_type`-style knob for it. Map a foreign issuer's
   agent identifier onto a local uuid inside the adapter. `user_id`
   carries no such constraint — it follows `c.user_id_type` (`Kiosk.configuration.user_id_type`).
 - **Postgres GUC namespace constants** — `Kiosk::GUC`
-- **Canonical-uuid shape guard** — `Kiosk::UuidCheck` (`valid?`)
+- **Canonical-uuid shape check** — `Kiosk::UuidCheck` (`valid?`)
 - **Protocol-version surface** — `Kiosk::Protocol` (API version, min client, response header names, default mount path)
 - **Configuration** — `Kiosk.configure { |c| ... }`
 
@@ -32,21 +32,19 @@ No Rails dependency. Loadable in any Ruby app. Heavier `kiosk-server`, `kiosk-rl
 
 ## Install
 
-> **Not on RubyGems yet** — so every `gem` line below carries `github: "kiosk-hq/kiosk"`, which is what makes it copy-pasteable today. Publication status and the canonical install are stated once, in the monorepo README's [Install](https://github.com/kiosk-hq/kiosk#install) section.
-
 ```ruby
-gem "kiosk-core", github: "kiosk-hq/kiosk"
+gem "kiosk-core"
 ```
 
-For the data plane (core + server), install the meta-gem — add RLS, payment, and IdP adapters per stack:
+For the data plane (core + server), install the meta-gem, then add RLS and the payment and identity adapters that your stack needs:
 
 ```ruby
-gem "kiosk-all", github: "kiosk-hq/kiosk"
+gem "kiosk-all"
 ```
 
 ## Status
 
-Pre-v1.0 alpha. Wire-protocol semver stability begins at v1.0; pre-v1.0 minor bumps may break compatibility (CHANGELOG.md tracks).
+Pre-v1.0 alpha. Protocol semver stability begins at v1.0; pre-v1.0 minor bumps may break compatibility (CHANGELOG.md tracks).
 
 ## License
 

data/lib/kiosk/agent_identity_providers/base.rb

@@ -5,7 +5,7 @@ module Kiosk
     # Base for an agent-IdP adapter fronting an external agent-identity issuer
     # (`c.agent_idp`). The engine calls only `verify`: it mints tokens and reads
     # mandate-signing keys through its bundled DefaultAgentIdp. The `agent_id` it
-    # returns must be a uuid: every schema column and `kiosk.current_agent_id()`
+    # returns must be a uuid: every `agent_id` column and `kiosk_current_agent_id()`
     # are typed `uuid`, so map foreign ids. The token comes as
     # `Authorization: DPoP <token>`, and the identity's `claims` carry
     # `cnf: { jkt: }`, the thumbprint of the key that must sign the request's

data/lib/kiosk/configuration.rb

@@ -3,42 +3,82 @@
 require 'uri'
 
 module Kiosk
-  # Host-application settings, filled via `Kiosk.configure`. Defaults suit a greenfield
-  # Rails app on the bundled agent-IdP; the provider supplies its own user
-  # model and (optionally) a user-IdP adapter.
+  # The settings of an origin, set in `config/initializers/kiosk.rb` with
+  # `Kiosk.configure { |c| ... }`. Each setting below says what it does, its
+  # default and an example. kiosk-server and the adapter gems add more settings.
   class Configuration
-    # Class name as a String, resolved at request time.
+    # The class name of your account model, as a String. Registration makes an
+    # account in it for each new assistant, and account binding finds the
+    # person's account in it. Required.
+    #   c.user_model = 'User'
     attr_accessor :user_model
 
-    # :uuid (default), :bigint, :integer or :text.
+    # The type of the primary key of `user_model`: :uuid, :bigint, :integer or
+    # :text. The kiosk tables and SQL functions store the account id in this
+    # type. Default :uuid. A table that Rails made with its default key is :bigint.
+    #   c.user_id_type = :bigint
     attr_accessor :user_id_type
 
-    # Nil in satellite mode: the provider's own frontend drives the wire endpoints.
+    # The adapter that tells which person is signed in on your own site, from
+    # the browser session. The account-binding pages read it: the page that
+    # makes a link code, the page that approves a device code, and the page
+    # that unlinks an assistant. Default nil: these pages refuse every person,
+    # so nobody can link an assistant to an account. With Devise, use the
+    # adapter of the kiosk-user-idp-devise gem.
+    #   c.user_idp = Kiosk::UserIdentityProviders::Devise.new
     attr_accessor :user_idp
 
-    # Nil uses kiosk-server's bundled DefaultAgentIdp; set only to front another agent-identity system.
+    # The adapter that verifies the access token of an assistant on each call.
+    # Default nil: kiosk-server verifies the tokens that its own token endpoint
+    # issues. Keep the default. Set it only when another system issues the
+    # tokens of the assistants. The value is a {Kiosk::AgentIdentityProviders::Base}.
+    #   c.agent_idp = MyTokenVerifier.new
     attr_accessor :agent_idp
 
-    # A {Kiosk::PaymentProviders::Base}; nil means no payment.
+    # The adapter that charges the card of a customer for a paid action, a
+    # {Kiosk::PaymentProviders::Base}. Default nil: the origin takes no money,
+    # and discovery does not list `pay`. The kiosk-pay-stripe gem gives Stripe.
+    #   c.payment_provider = Kiosk::PaymentProviders::Stripe.new(api_key: ENV.fetch('STRIPE_SECRET_KEY'))
     attr_accessor :payment_provider
 
-    # A {Kiosk::KycProviders::Base}; nil makes `request_kyc` answer `module_not_served`.
+    # The KYC service that confirms facts about a customer, for example an age
+    # over 18, a {Kiosk::KycProviders::Base}. Default nil: the action
+    # `request_kyc` answers `module_not_served`. The kiosk-kyc-proveli gem gives
+    # the Proveli broker.
+    #   c.kyc_provider = Kiosk::KycProviders::Proveli.new(operator_id: 'shop',
+    #     intake_secret: ENV.fetch('KIOSK_PROVELI_INTAKE_SECRET'), public_key: ENV.fetch('KIOSK_PROVELI_PUBLIC_KEY_PEM'))
     attr_accessor :kyc_provider
 
-    # Runtime DB role named in kiosk-rls GRANTs and `SET LOCAL ROLE`; the DBA creates it.
+    # The Postgres role that the opt-in kiosk-rls gem gives table access to,
+    # and that kiosk-server changes to with `SET LOCAL ROLE` when
+    # `enforce_db_role` is true. Your database administrator makes the role.
+    # Default 'app_role'. Without kiosk-rls and with `enforce_db_role` false
+    # (the default), nothing reads it: do not set it.
+    #   c.app_role = 'shop_app'
     attr_accessor :app_role
 
-    # E.g. `%i[customer master support]`. Never `:admin`.
+    # The roles that an assistant can get, as Symbols. A token carries one of
+    # them, and your code reads it to decide what the assistant can do. Name a
+    # role by the job of a person (customer, support), not by a power (admin).
+    # Default []: no token carries a role. Most origins need one role,
+    # %i[customer]. kiosk-server's `registration_role` names the role that a
+    # new assistant gets.
+    #   c.roles = %i[customer support]
     attr_accessor :roles
 
-    # The default origin served: `iss` of tokens and mandates, required proof `aud`,
-    # discovery `issuer`. Readers ask `Kiosk.current_issuer`.
+    # The origin of this deployment: scheme, host and port. It is the `iss` of
+    # the tokens and checkouts that the engine signs, the `aud` that the proof
+    # of an assistant must name, and the `issuer` of discovery. Required.
+    # Code reads it with `Kiosk.current_issuer`.
+    #   c.issuer = 'https://shop.example'
     attr_accessor :issuer
 
-    # Further origins, each a separate operator on the wire. Exact origins only;
-    # an alias of the SAME business is better redirected
+    # More origins, each a separate operator for the protocol, with its own
+    # discovery and its own assistant accounts. Exact origins only. Default [].
+    # A second name of the SAME business is better redirected
     # to the issuer at the edge. (Rails' `config.hosts` governs which Host
     # headers are accepted, not which origin the operator is.)
+    #   c.additional_origins = ['https://second-shop.example']
     attr_accessor :additional_origins
 
     def initialize

data/lib/kiosk/identity.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
 module Kiosk
-  # The principal making a request, as an IdP adapter's #verify returns it.
-  # `actor` is "agent", "human" or "service"; `agent_id` is present iff the
-  # actor is an agent and must be a uuid (the schema types it so, with no knob).
+  # The principal of a request, as the #verify of an identity adapter returns
+  # it. `actor` says who makes the request:
+  #   "agent"   — an AI assistant with an access token. kiosk-server makes it.
+  #   "human"   — a person signed in on the site of the operator. The `user_idp`
+  #               adapter makes it, for example kiosk-user-idp-devise.
+  # The audit sink receives the actor of each action, and an RLS policy reads
+  # it with `kiosk_current_actor()` (kiosk-rls).
+  # `agent_id` is the UUID of the assistant: present for an agent, nil otherwise.
   Identity = Data.define(:user_id, :role, :actor, :agent_id, :claims)
 
   # Validates user_id, actor and agent_id on construction.
   class Identity
-    VALID_ACTORS = %w[agent human service].freeze
+    VALID_ACTORS = %w[agent human].freeze
 
     def initialize(user_id:, role:, actor:, agent_id: nil, claims: {})
       actor = actor.to_s

data/lib/kiosk/kyc_providers/base.rb

@@ -1,18 +1,42 @@
 # frozen_string_literal: true
 
+require 'openssl'
+
 module Kiosk
   module KycProviders
     # The provider did not open a verification now; a later attempt may.
     class Unavailable < StandardError
     end
 
-    # Port for a KYC provider (`kiosk-kyc-*`); kiosk-server serves `request_kyc`
-    # whenever `Kiosk.configuration.kyc_provider` is set.
+    # The KYC provider an operator trusts, set as `Kiosk.configuration.kyc_provider`.
+    # It names the issuer, the Ed25519 key and the audience that the engine
+    # checks every attestation against. A `Base` accepts attestations at
+    # `POST <endpoint>/agents/kyc` only; an adapter (`kiosk-kyc-*`) that opens
+    # verifications also serves `request_kyc`.
     class Base
+      attr_reader :issuer, :public_key
+
+      # @param issuer [String] the `iss` the provider signs
+      # @param public_key [OpenSSL::PKey::PKey, String] its Ed25519 public key, or the key's PEM
+      # @param audience [String, nil] the `aud` it mints for this operator; nil: the origin being served
+      def initialize(issuer:, public_key:, audience: nil)
+        @issuer     = issuer.to_s
+        @public_key = public_key.is_a?(String) ? OpenSSL::PKey.read(public_key) : public_key
+        @audience   = audience
+        return if @public_key.is_a?(OpenSSL::PKey::PKey) && @public_key.oid == 'ED25519'
+
+        raise ArgumentError, "a KYC provider's public_key must be an Ed25519 key or its PEM, got #{@public_key.class}"
+      end
+
+      def audience = (@audience || Kiosk.current_issuer).to_s
+
+      # True when the provider opens verifications, so the engine serves `request_kyc`.
+      def opens_verifications? = false
+
       # The provider later POSTs `{request_id, nonce, kyc_jws}` to `callback_url`.
       # @return [Hash] `request_id:`, `verification_url:`, `nonce:`
       # @raise [Unavailable]
-      def open_verification(subject:, claims:, audience:, callback_url:)
+      def open_verification(subject:, claims:, callback_url:)
         raise NotImplementedError, "#{self.class}#open_verification must be implemented by the adapter"
       end
 

data/lib/kiosk/protocol.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Kiosk
-  # Wire-protocol version and header names.
+  # Protocol version and header names.
   module Protocol
     # Before 1.0 every gem and every pinned skill cut carry this exact version (spec §14.1).
-    API_VERSION = '0.6.1'
+    API_VERSION = '0.6.28'
 
     # The oldest skill cut that works with this release: same MAJOR.MINOR as
     # API_VERSION, no newer (spec §3.6). Advisory.

data/lib/kiosk/uuid_check.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Kiosk
-  # Shape check for wire-supplied uuids, so a malformed id is a typed 4xx rather
+  # Shape check for request-supplied uuids, so a malformed id is a typed 4xx rather
   # than a 500 from Postgres or a false ownership refusal from Active Record's
   # NULL cast. Format only: it says nothing about whether the row exists.
   module UuidCheck

data/lib/kiosk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kiosk
-  VERSION = '0.6.1'
+  VERSION = '0.6.28'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiosk-core
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.28
 platform: ruby
 authors:
 - Phil Pirozhkov