kiosk-server 0.5.20 → 0.6.1

data/lib/kiosk/server/checkout.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'securerandom'
+
+module Kiosk
+  module Server
+    # The checkout an operator answers for an item to pay for: a JWT it signs
+    # EdDSA with its signing key. The assistant's checkout mandate names it by
+    # hash. EdDSA signatures are deterministic, so a random `jti` makes the hash
+    # of each checkout impossible to guess (AP2 v0.2, rainbow table attacks).
+    module Checkout
+      ALGORITHM = Eddsa::NAME
+
+      module_function
+
+      # @param user_id the account the checkout is for; only that account can pay it
+      # @return [String] the compact JWT
+      def sign(user_id:, currency:, total_amount_cents:, line_items:)
+        signed({ iss: Kiosk.current_issuer, sub: user_id.to_s, iat: Time.now.to_i, jti: SecureRandom.urlsafe_base64(16),
+                 merchant: merchant, currency: currency, total_amount_cents: total_amount_cents, line_items: line_items })
+      end
+
+      # @return [String] `claims` as a compact JWT, signed EdDSA with the operator's signing key
+      def signed(claims)
+        key = Kiosk.configuration.signing_key
+        ::JWT.encode(claims, key.key, ALGORITHM, { kid: key.kid, typ: 'JWT' })
+      end
+
+      # The AP2 Merchant object: the payee the payment mandate names.
+      def merchant
+        issuer = Kiosk.current_issuer
+        { id: issuer, name: Kiosk.configuration.owner[:name] || issuer, website: issuer }
+      end
+
+      # @return [Hash] the claims of a checkout this origin signed, with its current or previous key, for this account
+      # @raise [Errors::Forbidden]
+      def verify(checkout_jwt, identity:)
+        claims = decode(checkout_jwt)
+        raise Errors::Forbidden.new('checkout is not from this origin', hint: ISSUER_HINT) unless claims['iss'] == Kiosk.current_issuer
+        return claims if claims['sub'] == identity.user_id.to_s
+
+        raise Errors::Forbidden.new('checkout is for another account', hint: 'pay only a checkout this operator answered to you')
+      rescue ::JWT::DecodeError
+        raise Errors::Forbidden.new('checkout_jwt signature invalid', hint: ISSUER_HINT)
+      end
+
+      # The claims of a checkout that the current or the previous signing key signed.
+      def decode(checkout_jwt)
+        jwks = Jwks.build(keys: Kiosk.configuration.signing_keys)
+        ::JWT.decode(checkout_jwt, nil, true, algorithms: [ALGORITHM]) { |header| Jwks.find(jwks, header['kid']) }.first
+      end
+
+      ISSUER_HINT = 'send the checkout_jwt this operator answered, unchanged'
+    end
+  end
+end

data/lib/kiosk/server/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'active_record'
+
+module Kiosk
+  module Server
+    # A registered OAuth client: one live row of the agents table at the origin
+    # of this request. Its `id` is both the `client_id` and the `agent_id`.
+    class Client < Data.define(:id, :user_id, :public_key_pem, :allowed_roles, :issued_at)
+      UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+      CLIENT_CREDENTIALS = 'client_credentials'
+      DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code'
+
+      AUTH_METHOD = 'private_key_jwt'
+
+      # The grant types this origin serves, so the grant types of every client.
+      def self.grant_types(config = Kiosk.configuration)
+        config.serve_account_binding ? [CLIENT_CREDENTIALS, DEVICE_CODE] : [CLIENT_CREDENTIALS]
+      end
+
+      # nil for an id that is not a UUID, so the database never sees it.
+      def self.find(id)
+        lookup('id = $1', id.to_s) if UUID.match?(id.to_s)
+      end
+
+      def self.with_key(key)
+        lookup('public_key = $1', AssistantKey.to_pem(key))
+      end
+
+      def self.lookup(condition, value)
+        row = ::ActiveRecord::Base.lease_connection.exec_query(<<~SQL.squish, 'Kiosk client lookup', [value, Kiosk.current_issuer]).to_a.first
+          SELECT id, user_id, public_key, allowed_roles, extract(epoch FROM created_at)::bigint AS issued_at
+          FROM #{Kiosk.configuration.schema}.agents
+          WHERE #{condition} AND issuer = $2 AND revoked_at IS NULL
+          LIMIT 1
+        SQL
+        row && new(id: row['id'], user_id: row['user_id'], public_key_pem: row['public_key'],
+                   allowed_roles: row['allowed_roles'], issued_at: row['issued_at'].to_i)
+      end
+      private_class_method :lookup
+
+      def key = AssistantKey.from_pem(public_key_pem)
+
+      def thumbprint = AssistantKey.thumbprint(key)
+
+      # The first role. `allowed_roles` is an Array or a text[] literal ("{customer}"), by adapter.
+      def role
+        roles = allowed_roles.is_a?(Array) ? allowed_roles : allowed_roles.to_s.delete('{}').split(',')
+        roles.first
+      end
+
+      # The RFC 7591 Section 3.2.1 client information response.
+      def information
+        { client_id: id, client_id_issued_at: issued_at, jwks: { keys: [AssistantKey.to_jwk(key)] },
+          token_endpoint_auth_method: AUTH_METHOD, grant_types: self.class.grant_types,
+          dpop_bound_access_tokens: true }
+      end
+    end
+  end
+end

data/lib/kiosk/server/client_assertion.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'rails'
+
+module Kiosk
+  module Server
+    # Client authentication by `private_key_jwt`: an RFC 7523 client assertion
+    # that the registered key of the client signs. Each refusal says what to fix.
+    module ClientAssertion
+      TYPE = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+
+      # Seconds: the longest life an assertion can have, and the clock difference accepted.
+      MAX_LIFETIME = 300
+      LEEWAY = 60
+
+      REQUIRED_CLAIMS = %w[iss sub aud exp jti].freeze
+
+      # A refused client assertion. The `/oauth/*` endpoints answer it as
+      # `invalid_client`, the other endpoints as `401 unauthenticated`.
+      class Refused < StandardError
+        attr_reader :hint
+
+        def initialize(message, hint:)
+          @hint = hint
+          super(message)
+        end
+
+        def to_oauth = OauthError.new(:invalid_client, "#{message}: #{hint}")
+        def to_problem = Errors::Unauthenticated.new(message, hint: hint)
+      end
+
+      # A verified assertion that is not yet spent.
+      Verified = Data.define(:client, :claims)
+
+      # Names no origin: a value that a response sends back is what a relaying server would exploit.
+      AUDIENCE_HINT = 'sign `aud` = the origin you connected to, taken from your own request URL, ' \
+                      'never from a value that a response sends back'
+
+      CLAIMS_HINT = "the payload carries #{REQUIRED_CLAIMS.join(', ')}: `iss` and `sub` are your client_id, " \
+                    '`aud` is the origin you connected to, `exp` is at most 300 seconds from now, ' \
+                    '`jti` is a new unique id'.freeze
+
+      UNKNOWN_CLIENT_HINT = 'register your key at registration_url; the answer carries your client_id. ' \
+                            'A client that the account holder unlinked is unknown'
+
+      SIGNATURE_HINT = 'a client assertion is a compact JWS that the private key of your registered key signs: ' \
+                       'EdDSA for an Ed25519 key, ES256 for a P-256 key'
+
+      module_function
+
+      # Verifies and spends the assertion; answers its client.
+      # @raise [Refused]
+      def authenticate!(type, assertion, client_id: nil)
+        verified = verify(type, assertion, client_id: client_id)
+        spend!(verified)
+        verified.client
+      end
+
+      # Every check but the single use. `key` replaces the registered key: a
+      # rotation verifies the assertion of the new key with it.
+      # @raise [Refused]
+      def verify(type, assertion, client_id: nil, key: nil)
+        check_type!(type, assertion)
+        client = client_of(assertion)
+        claims = decode(assertion, key || registered_key(client))
+        check_claims!(claims, client_id)
+        Verified.new(client: client, claims: claims)
+      end
+
+      # Claims the `jti` in the spent-id set until the assertion can no longer be accepted.
+      # @raise [Refused] when the `jti` is spent already
+      def spend!(verified)
+        id = "client_assertion:#{verified.client.id}:#{verified.claims['jti']}"
+        return if Kiosk.configuration.pow_spent_store.claim(id, verified.claims['exp'].to_i + LEEWAY)
+
+        refuse!('client assertion already used', 'sign a new client assertion with a new `jti` for each request')
+      end
+
+      def check_type!(type, assertion)
+        if assertion.to_s.empty?
+          refuse!('client authentication required',
+                  "send client_assertion_type = #{TYPE} and client_assertion, a JWT that your registered key signs")
+        end
+        refuse!('unsupported client_assertion_type', "send client_assertion_type = #{TYPE}") unless type == TYPE
+      end
+
+      # The client the `sub` names. The signature is checked after this, with its key.
+      def client_of(assertion)
+        payload = ::JWT.decode(assertion.to_s, nil, false).first
+        Client.find(payload.is_a?(Hash) ? payload['sub'] : nil) || refuse!('unknown client', UNKNOWN_CLIENT_HINT)
+      rescue ::JWT::DecodeError
+        refuse!('client assertion is not a JWT', SIGNATURE_HINT)
+      end
+
+      # A key that this operator accepts no longer, such as a P-256 key once ES256 is off.
+      def registered_key(client)
+        client.key
+      rescue Errors::BadRequest
+        refuse!('the registered key is not accepted here',
+                "this operator accepts #{AssistantKey.algorithms.join(' and ')} keys: register a new key at registration_url")
+      end
+
+      def decode(assertion, key)
+        ::JWT.decode(assertion.to_s, key, true, algorithms: [AssistantKey.algorithm(key)],
+                                                required_claims: REQUIRED_CLAIMS, leeway: LEEWAY).first
+      rescue ::JWT::IncorrectAlgorithm
+        refuse!("client assertion alg is not #{AssistantKey.algorithm(key)}, the algorithm of your registered key", SIGNATURE_HINT)
+      rescue ::JWT::MissingRequiredClaim
+        refuse!('client assertion is missing a required claim', CLAIMS_HINT)
+      rescue ::JWT::ExpiredSignature
+        refuse!('client assertion expired', 'sign a new client assertion')
+      rescue ::JWT::DecodeError
+        refuse!('client assertion signature invalid', SIGNATURE_HINT)
+      end
+
+      def check_claims!(claims, client_id)
+        refuse!('client assertion iss is not its sub', CLAIMS_HINT) unless claims['iss'] == claims['sub']
+        refuse!('client_id is not the client assertion sub', CLAIMS_HINT) if client_id.present? && client_id != claims['sub']
+        check_audience!(claims['aud'])
+        return if claims['exp'].to_i <= Time.now.to_i + MAX_LIFETIME
+
+        refuse!('client assertion lives too long', "set `exp` at most #{MAX_LIFETIME} seconds after now")
+      end
+
+      # `aud` names this origin as its only value (RFC 7523bis Section 4).
+      def check_audience!(aud)
+        issuer = Kiosk.current_issuer
+        return if Array(aud) == [issuer]
+
+        log_audience_mismatch(aud, issuer)
+        refuse!('client assertion audience mismatch', AUDIENCE_HINT)
+      end
+
+      # Operator log only, because the answer must not name an origin: the
+      # caller signed a wrong value, or this deployment does not serve the origin it reached.
+      def log_audience_mismatch(aud, issuer)
+        message = "[kiosk] client assertion audience mismatch: the caller signed aud=#{aud.inspect}, " \
+                  "the issuer for this request is #{issuer.inspect}. If the signed value is an origin " \
+                  'your assistants actually reach, list it in `c.issuer` or `c.additional_origins`.'
+        logger = ::Rails.logger
+        logger ? logger.warn(message) : warn(message)
+      end
+
+      def refuse!(message, hint)
+        raise Refused.new(message, hint: hint)
+      end
+
+      private_class_method :check_type!, :client_of, :registered_key, :decode, :check_claims!, :check_audience!,
+                           :log_audience_mismatch, :refuse!
+    end
+  end
+end

data/lib/kiosk/server/client_registration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support/core_ext/string/inflections' # String#constantize
+
+module Kiosk
+  module Server
+    # RFC 7591 open registration of an AI assistant's public key, with no human:
+    # creates the assistant account and its client. A key with a live client
+    # gets that client again, so an assistant that lost its client_id recovers it.
+    module ClientRegistration
+      module_function
+
+      # @param metadata [Hash] the parsed request body
+      # @return [Client]
+      # @raise [OauthError] `invalid_client_metadata`
+      def call(metadata, pow: nil)
+        config = Kiosk.configuration
+        role   = registration_role(config)
+        key    = checked_key(metadata)
+
+        AuthToll.gate(verb: 'oauth/register', body: { key: AssistantKey.thumbprint(key) }, pow: pow, config: config)
+        Client.with_key(key) || register(config, key, role)
+      end
+
+      def checked_key(metadata)
+        invalid!('the request body must be a JSON object') unless metadata.is_a?(Hash)
+        metadata = metadata.transform_keys(&:to_s)
+        method = metadata['token_endpoint_auth_method']
+        invalid!("token_endpoint_auth_method must be #{Client::AUTH_METHOD}") unless [nil, Client::AUTH_METHOD].include?(method)
+        check_grant_types!(metadata['grant_types'])
+        AssistantKey.from_jwks(metadata['jwks'])
+      rescue Errors::BadRequest => e
+        invalid!("jwks: #{e.message}; #{e.hint}")
+      end
+
+      def check_grant_types!(grant_types)
+        return if grant_types.nil?
+        return if grant_types.is_a?(Array) && (grant_types - Client.grant_types).empty?
+
+        invalid!("grant_types must be a list of the grant types this origin serves: #{Client.grant_types.join(', ')}")
+      end
+
+      # The operator's `assistant_creation` factory, else a bare `user_model.create!`.
+      def create_assistant_account(config, pem)
+        return config.user_model.constantize.create!.id unless config.assistant_creation
+
+        id = config.assistant_creation.call(pem)
+        return id unless id.nil?
+
+        raise Errors::ConfigurationError,
+              'config.assistant_creation returned nil. The block must create the ' \
+              'assistant account and RETURN its id (used as agents.user_id), e.g. ' \
+              'c.assistant_creation = ->(pubkey) { AssistantAccount.create!(...).id }'
+      end
+
+      # The role is the server's choice, never the assistant's.
+      def registration_role(config)
+        role = config.registration_role&.to_s
+        return if role.blank?
+        return role if config.roles.map(&:to_s).include?(role)
+
+        raise Errors::ConfigurationError,
+              "registration_role #{role.inspect} is not among configured roles " \
+              "#{config.roles.inspect}"
+      end
+
+      # The live unique index on (issuer, public_key) picks the winner of a race.
+      def register(config, key, role)
+        pem = AssistantKey.to_pem(key)
+        conn = ::ActiveRecord::Base.lease_connection
+        conn.transaction(requires_new: true) { insert_agent(conn, config, [create_assistant_account(config, pem), pem], role) }
+        Client.with_key(key)
+      rescue ::ActiveRecord::RecordNotUnique
+        Client.with_key(key)
+      end
+
+      # No role is the empty array: `allowed_roles` is NOT NULL.
+      def insert_agent(conn, config, binds, role)
+        allowed_roles_sql, role_binds = role ? ['ARRAY[$4]::text[]', [role]] : ["'{}'::text[]", []]
+        conn.exec_query(<<~SQL.squish, 'Kiosk agent insert', [*binds, Kiosk.current_issuer, *role_binds])
+          INSERT INTO #{config.schema}.agents (user_id, public_key, issuer, allowed_roles)
+          VALUES ($1, $2, $3, #{allowed_roles_sql})
+        SQL
+      end
+
+      def invalid!(description)
+        raise OauthError.new(:invalid_client_metadata, description)
+      end
+
+      private_class_method :checked_key, :check_grant_types!, :registration_role, :register, :insert_agent, :invalid!
+    end
+  end
+end

data/lib/kiosk/server/configuration_extension.rb

@@ -35,7 +35,7 @@ module Kiosk
         attr_writer :skill_url
 
         def skill_url
-          @skill_url ||= 'https://kiosk.tech/skill-v0.5.20.md'
+          @skill_url ||= 'https://kiosk.tech/skill-v0.6.1.md'
         end
         attr_accessor :skill_sha256
 
@@ -57,7 +57,7 @@ module Kiosk
 
       # The proof-of-work settings: registration proofs and the reputation challenge.
       module ProofOfWork
-        # Equihash proofs asked at `POST /auth/register`, at the link-code claim and
+        # Equihash proofs asked at `POST /oauth/register`, at the link-code claim and
         # at the first token poll of each device code, at the gem's default params.
         # Default 0 (open). Above 0 needs `pow_secret` and `kiosk-pow-equihash`.
         attr_writer :registration_pow_count
@@ -122,20 +122,16 @@ module Kiosk
           @kyc_audience || Kiosk.current_issuer
         end
 
-        # The KYC provider's RSA key: an OpenSSL::PKey or a PEM string.
+        # The KYC provider's Ed25519 public key: an OpenSSL::PKey or a PEM string.
         def kyc_public_key
           @kyc_public_key
         end
 
         def kyc_public_key=(value)
-          @kyc_public_key = case value
-                            when OpenSSL::PKey::PKey then value
-                            when String              then OpenSSL::PKey::RSA.new(value)
-                            when nil                 then nil
-                            else
-                              raise ArgumentError,
-                                    "kyc_public_key must be an OpenSSL::PKey or PEM string, got #{value.class}"
-                            end
+          @kyc_public_key = value.is_a?(String) ? OpenSSL::PKey.read(value) : value
+          return if @kyc_public_key.nil? || Jwk.ed25519?(@kyc_public_key)
+
+          raise ArgumentError, "kyc_public_key must be an Ed25519 key or its PEM string, got #{@kyc_public_key.class}"
         end
       end
 
@@ -169,27 +165,50 @@ module Kiosk
       include Kyc
       include Database
 
-      # Required. A SigningKey or a PEM string.
+      # Required. A SigningKey or the PEM string of an Ed25519 key.
       def signing_key
         @signing_key || raise(Errors::ConfigurationError,
-                              'c.signing_key is not set. Generate one with `openssl genrsa 2048`.')
+                              "c.signing_key is not set. #{SigningKey::HINT.capitalize}.")
       end
 
       def signing_key=(value)
-        @signing_key = case value
-                       when Kiosk::Server::SigningKey, nil then value
-                       when String then Kiosk::Server::SigningKey.from_pem(value)
-                       else raise ArgumentError, "signing_key must be a SigningKey or PEM string, got #{value.class}"
-                       end
+        @signing_key = signing_key_from(value, 'signing_key')
+      end
+
+      # Optional. The key that signed before {#signing_key}: the JWKS still
+      # publishes it, and a token or checkout it signed still verifies. A public
+      # PEM is enough. Keep it for at least one access-token lifetime, and while
+      # a checkout it signed can still be paid.
+      attr_reader :previous_signing_key
+
+      def previous_signing_key=(value)
+        @previous_signing_key = signing_key_from(value, 'previous_signing_key')
       end
 
-      # The role every self-registered agent is pinned to, and the default a
+      # The keys the JWKS publishes and verification accepts, the current one first.
+      def signing_keys = [signing_key, previous_signing_key].compact
+
+      # The JOSE algorithms an AI assistant can sign with. Default `["EdDSA"]`:
+      # Ed25519 keys only. `%w[EdDSA ES256]` also accepts P-256 keys.
+      def assistant_algorithms
+        @assistant_algorithms || [Eddsa::NAME]
+      end
+
+      def assistant_algorithms=(value)
+        algorithms = Array(value).map(&:to_s)
+        valid = [[Eddsa::NAME], [Eddsa::NAME, 'ES256']].include?(algorithms)
+        raise Errors::ConfigurationError, "c.assistant_algorithms is %w[EdDSA] or %w[EdDSA ES256], got #{algorithms.inspect}" unless valid
+
+        @assistant_algorithms = algorithms.freeze
+      end
+
+      # The role every registered client is pinned to, and the default a
       # binding falls back to. Required, and one of {#roles}, when {#roles} is set.
       #   Kiosk.configure { |c| c.roles = %i[customer]; c.registration_role = :customer }
       attr_accessor :registration_role
 
-      # Optional `->(public_key) { record_id }` creating the account behind a
-      # self-registered agent. Unset: `user_model.constantize.create!`.
+      # Optional `->(public_key_pem) { record_id }` creating the account behind a
+      # registered client. Unset: `user_model.constantize.create!`.
       attr_accessor :assistant_creation
 
       # Account-binding ceremony state. Default: the shared database store.
@@ -224,7 +243,7 @@ module Kiosk
         true
       end
 
-      # Called as `(agent:, from:, to:)` when an assistant's key moves from one
+      # Called as `(agent:, from:, to:)` when an assistant's client moves from one
       # account to another, inside the rebind transaction: the place to move
       # the operator's own rows. `from` and `to` are `user_model` records.
       attr_accessor :assistant_claimed
@@ -234,7 +253,7 @@ module Kiosk
       attr_accessor :assistant_unlinked
 
       # Optional `(agent_id:) → { amount_cents:, currency: } | nil`, checked
-      # before capture; 0 blocks payments, and so does a cart in another currency.
+      # before capture; 0 blocks payments, and so does a checkout in another currency.
       # {Kiosk::Server::ColumnSpendingCap} reads
       # `agents.spending_cap_cents`, the column edited by the manage-assistants
       # page, and `agents.spending_cap_currency`.
@@ -243,8 +262,8 @@ module Kiosk
       # Days of settled spend summed against the cap. Default nil: all time.
       attr_accessor :spending_cap_window_days
 
-      # `call(id, lines) → cents | String`: the payable row's price, or why the cart is refused.
-      attr_accessor :cart_price_checker
+      # `call(id, lines) → cents | String`: the payable row's price, or why the checkout is refused.
+      attr_accessor :checkout_price_checker
 
       # Optional `call(id)`, run once the settlement that paid row `id` is recorded.
       attr_accessor :after_payment
@@ -282,7 +301,8 @@ module Kiosk
         @audit_sink = value
       end
 
-      # Spent challenge ids, so a proof is accepted once. Default: the shared database table.
+      # Spent ids, so a proof-of-work proof or a client assertion is accepted once.
+      # Default: the shared database table.
       attr_writer :pow_spent_store
 
       def pow_spent_store
@@ -290,16 +310,6 @@ module Kiosk
           LAZY_STORE_MUTEX.synchronize { @pow_spent_store ||= Kiosk::Server::PowSpentStores::ActiveRecord.new }
       end
 
-      # Outstanding auth nonces. Default: the shared database table.
-      attr_writer :auth_challenge_store
-
-      def auth_challenge_store
-        @auth_challenge_store ||
-          LAZY_STORE_MUTEX.synchronize do
-            @auth_challenge_store ||= Kiosk::Server::AuthChallengeStores::ActiveRecord.new
-          end
-      end
-
       # Seconds an access token lives. One paid proof-of-work toll lasts as long. Default 3600.
       attr_writer :access_token_ttl
 
@@ -307,14 +317,6 @@ module Kiosk
         @access_token_ttl ||= JwtIssuer::DEFAULT_EXPIRES_IN
       end
 
-      # Seconds between `GET /auth/challenge` and the signed POST. Default covers
-      # the auth toll's proof-of-work window plus 60s.
-      attr_writer :auth_challenge_ttl
-
-      def auth_challenge_ttl
-        @auth_challenge_ttl ||= (pow_ttl * [registration_pow_count.to_i, 1].max) + 60
-      end
-
       # Revocation watermarks, checked on every access token. Default: the
       # shared database table, so a revoke or an unlink holds in every process.
       attr_writer :revocation_store
@@ -323,6 +325,16 @@ module Kiosk
         @revocation_store ||
           LAZY_STORE_MUTEX.synchronize { @revocation_store ||= Kiosk::Server::RevocationStores::ActiveRecord.new }
       end
+
+      private
+
+      def signing_key_from(value, name)
+        case value
+        when Kiosk::Server::SigningKey, nil then value
+        when String then Kiosk::Server::SigningKey.from_pem(value)
+        else raise ArgumentError, "#{name} must be a SigningKey or PEM string, got #{value.class}"
+        end
+      end
     end
   end
 end