kiosk-server 0.5.20 → 0.6.28

data/lib/kiosk/server/assistant_accounts.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The accounts that the engine opened for assistants at registration, in
+    # `assistant_accounts`. The first binding of the assistant merges its
+    # assistant account into the human's account: from then on the spend of
+    # the human's account includes the settlements and visits of the assistant
+    # account. Unlinking the assistant later keeps the merge.
+    module AssistantAccounts
+      module_function
+
+      # Records `user_id` as the account of a new assistant. An account that
+      # `assistant_creation` gave to an earlier key is recorded once.
+      def record!(user_id)
+        connection.exec_query(%(INSERT INTO "#{schema}".kiosk_assistant_accounts (user_id) VALUES ($1) ON CONFLICT DO NOTHING),
+                              'Kiosk assistant account', [user_id])
+        nil
+      end
+
+      # Merges the account `from` into the account `into` when `from` is an
+      # assistant account that is not merged yet. A binding moves an assistant
+      # to the account of the approving human, which is never an assistant
+      # account: so the account of one human never merges into the account of
+      # another, and merges do not form chains.
+      def merge!(from:, into:)
+        connection.exec_query(<<~SQL.squish, 'Kiosk assistant account merge', [from, into])
+          UPDATE "#{schema}".kiosk_assistant_accounts SET merged_into = $2, merged_at = now()
+          WHERE user_id = $1 AND merged_into IS NULL
+        SQL
+        nil
+      end
+
+      def connection = ::ActiveRecord::Base.lease_connection
+      def schema = Kiosk.configuration.schema
+    end
+  end
+end

data/lib/kiosk/server/assistant_key.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Kiosk
+  module Server
+    # The public key of an AI assistant: the key it registers, signs its client
+    # assertions, DPoP proofs and mandates with, and binds its tokens to. An
+    # Ed25519 key signs EdDSA. A P-256 key signs ES256 where the operator
+    # accepts ES256 (`c.assistant_algorithms`).
+    module AssistantKey
+      # The members of a JWK that only a private key has.
+      PRIVATE_MEMBERS = %w[d].freeze
+
+      module_function
+
+      # The algorithms this operator accepts, EdDSA first. Client assertions,
+      # DPoP proofs, mandates and every metadata list read this list.
+      def algorithms = Kiosk.configuration.assistant_algorithms
+
+      def hint
+        keys = ['an Ed25519 key as an RFC 8037 JWK {"kty":"OKP","crv":"Ed25519","x":"…"}']
+        keys << 'a P-256 key as an RFC 7518 JWK {"kty":"EC","crv":"P-256","x":"…","y":"…"}' if algorithms.include?('ES256')
+        "send one public key: #{keys.join(', or ')}, with no private member"
+      end
+
+      # The key of an RFC 7517 JWK Set that holds exactly one public key.
+      # @raise [Errors::BadRequest] naming what is wrong
+      def from_jwks(jwks)
+        keys = jwks.is_a?(Hash) ? (jwks['keys'] || jwks[:keys]) : nil
+        refuse!('jwks must be a JWK Set with exactly one key') unless keys.is_a?(Array) && keys.size == 1
+
+        from_jwk(keys.first)
+      end
+
+      # @raise [Errors::BadRequest] naming what is wrong
+      def from_jwk(jwk)
+        refuse!('the key is not a JWK object') unless jwk.is_a?(Hash)
+        jwk = jwk.transform_keys(&:to_s)
+        refuse!('the key carries a private member') if jwk.keys.intersect?(PRIVATE_MEMBERS)
+        refuse!("the key is not an #{curves} key") unless key_types.include?(jwk['kty'])
+
+        accepted(Jwk.import(jwk))
+      rescue ArgumentError => e
+        refuse!(e.message)
+      end
+
+      # The key of a row of the agents table.
+      # @raise [Errors::BadRequest] when this operator does not accept the key
+      def from_pem(pem)
+        accepted(OpenSSL::PKey.read(pem.to_s))
+      rescue OpenSSL::PKey::PKeyError
+        refuse!('the key is not a valid public key')
+      end
+
+      # The form the agents table stores.
+      def to_pem(key) = key.public_to_pem.strip
+
+      # RFC 7517: the public members only.
+      def to_jwk(key) = Jwk.public_members(key)
+
+      # RFC 7638.
+      def thumbprint(key) = Jwk.thumbprint(key)
+
+      # The one algorithm `key` signs with.
+      def algorithm(key) = Jwk.algorithm(key)
+
+      # `OKP`, and `EC` where ES256 is accepted.
+      def key_types = algorithms.map { Jwk::ALGORITHMS.key(it) }
+
+      def curves = key_types.map { Jwk::CURVES[it] }.join(' or ')
+
+      def accepted(key)
+        refuse!('the key is a private key') if Jwk.private?(key)
+        refuse!("the key is not an #{curves} key") unless algorithms.include?(algorithm(key))
+        key
+      end
+
+      def refuse!(detail)
+        raise Errors::BadRequest.new(detail, hint: hint)
+      end
+
+      private_class_method :key_types, :curves, :accepted, :refuse!
+    end
+  end
+end

data/lib/kiosk/server/auth_toll.rb

@@ -3,17 +3,17 @@
 module Kiosk
   module Server
     # Optional proof-of-work toll on the auth requests that come before a
-    # token: `POST /auth/register`, the link-code claim `POST /auth/claim`, and
+    # token: `POST /oauth/register`, the link-code claim `POST /auth/claim`, and
     # the first token poll of each device code. It runs before any lookup, so
-    # the answer never tells a caller whether a key or a code exists. It bounds
-    # the cost per request, not the rate: an edge rate limit is required
-    # (deploy/README.md "Edge rate-limit").
+    # the answer never tells a caller whether a key or a code exists. It sets
+    # the cost of each request, not a rate. The shipped deploy has no edge rate
+    # limit (deploy/README.md "Edge rate-limit").
     module AuthToll
       module_function
 
       def on?(config = Kiosk.configuration) = config.registration_pow_count.to_i.positive?
 
-      # `verb` and `body` make the fingerprint, so a proof pays for this request only.
+      # `verb` and `body` make the fingerprint, so a proof clears the toll of this request only.
       def gate(verb:, body:, pow:, config: Kiosk.configuration)
         return unless on?(config)
 
@@ -26,7 +26,7 @@ module Kiosk
       end
 
       def secret!(config)
-        unless defined?(::Kiosk::Reputation) && defined?(::Kiosk::Pow::Equihash)
+        unless defined?(::Kiosk::Reputation::Challenge) && defined?(::Kiosk::Pow::Equihash.params)
           raise Errors::ConfigurationError,
                 'registration_pow_count > 0 requires kiosk-reputation and kiosk-pow-equihash. ' \
                 'Add both gems (and `require` them) to your app.'

data/lib/kiosk/server/binding_module_gate.rb

@@ -7,7 +7,7 @@ module Kiosk
     # `/oauth/*` it is the one problem document served instead of an OAuth error.
     module BindingModuleGate
       DETAIL = 'this operator does not serve the account binding module'
-      HINT   = "register a fresh assistant account at this origin's register_url instead"
+      HINT   = "use this origin with a client of your own: register it at this origin's registration_url"
 
       private
 

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}.kiosk_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,154 @@
+# 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` with the
+      # `Kiosk-Client-Assertion` challenge.
+      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::ClientAssertionRefused.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,98 @@
+# 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) do
+          account = create_assistant_account(config, pem)
+          AssistantAccounts.record!(account)
+          insert_agent(conn, config, [account, pem], role)
+        end
+        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}.kiosk_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/column_spending_cap.rb

@@ -14,7 +14,7 @@ module Kiosk
         # The leased connection: the cap is read inside the transaction that charges.
         row = ::ActiveRecord::Base.lease_connection.exec_query(<<~SQL.squish, 'Kiosk spending cap', [agent_id]).to_a.first
           SELECT spending_cap_cents, spending_cap_currency
-          FROM "#{Kiosk.configuration.schema}".agents
+          FROM "#{Kiosk.configuration.schema}".kiosk_agents
           WHERE id = $1 AND revoked_at IS NULL
         SQL
         return nil if row.nil? || row['spending_cap_cents'].nil?