kiosk-server 0.5.20

data/lib/kiosk/server/headers.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The Kiosk response headers and the cache policy of a wire response.
+    module Headers
+      def self.add_to(headers, server_version: Kiosk::Server::VERSION)
+        headers[Kiosk::Protocol::HEADER_SERVER_VERSION] = server_version
+        headers[Kiosk::Protocol::HEADER_API_VERSION]    = Kiosk::Protocol::API_VERSION
+        headers[Kiosk::Protocol::HEADER_MIN_CLIENT]     = Kiosk::Protocol::MIN_CLIENT
+        headers
+      end
+
+      def self.build(server_version: Kiosk::Server::VERSION)
+        add_to({}, server_version: server_version)
+      end
+
+      # §3.7.1: every one of these changes the answer and none is in the URL.
+      WIRE_VARY = %w[Authorization Kiosk-PoW Kiosk-Timezone].freeze
+
+      # Adds the wire `Vary`; forces `no-store` on a 402; defaults to
+      # `private, no-store` and refuses a shared-cache directive (§3.7.3).
+      def self.add_cache_policy(headers, status:)
+        add_wire_vary(headers)
+        policy = wire_cache_control(headers['Cache-Control'].to_s, status)
+        headers['Cache-Control'] = policy if policy
+        headers
+      end
+
+      def self.add_wire_vary(headers)
+        present = headers['Vary'].to_s.split(',').map(&:strip).reject(&:empty?)
+        missing = WIRE_VARY.reject { |t| present.any? { |p| p.casecmp?(t) } }
+        headers['Vary'] = (present + missing).join(', ')
+      end
+
+      # nil keeps the operator's own policy.
+      def self.wire_cache_control(operator, status)
+        return 'no-store' if status.to_i == 402
+        return 'private, no-store' if operator.empty?
+        return unless shared_cacheable?(operator)
+
+        refuse_shared_cache(operator)
+        'private, no-store'
+      end
+
+      # RFC 9111 §3.5: the directives that let a shared cache reuse an answer
+      # to an authenticated request.
+      SHARED_CACHE_DIRECTIVES = /\b(?:public|s-maxage|must-revalidate)\b/i
+
+      def self.shared_cacheable?(cache_control)
+        SHARED_CACHE_DIRECTIVES.match?(cache_control.to_s)
+      end
+
+      SHARED_CACHE_RULE =
+        'A verb response is for one caller, so a shared cache must not keep it. ' \
+        'Sent `private, no-store` instead; send `private, max-age=N` to let the caller cache it.'
+
+      def self.refuse_shared_cache(value)
+        message = '[kiosk-server] refused a shared-cache policy on a wire response: ' \
+                  "Cache-Control: #{value.inspect}. #{SHARED_CACHE_RULE}"
+        logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+        logger ? logger.warn(message) : warn(message)
+      end
+
+      # The public documents (`/schema`, `/openapi.json`): a short TTL on the
+      # fixed URL, a year on the digest-versioned `?v=` one.
+      SHORT_MAX_AGE     = 60
+      IMMUTABLE_MAX_AGE = 31_536_000
+
+      # Spelt in the order ActionDispatch re-emits the header.
+      PUBLIC_SHORT     = "max-age=#{SHORT_MAX_AGE}, public".freeze
+      PUBLIC_IMMUTABLE = "max-age=#{IMMUTABLE_MAX_AGE}, public, immutable".freeze
+
+      # Sets no `Vary`: a public document has one answer for every caller.
+      def self.add_public_cache_policy(headers, etag:, immutable:)
+        headers['Cache-Control'] = immutable ? PUBLIC_IMMUTABLE : PUBLIC_SHORT
+        headers['ETag'] = etag
+        headers
+      end
+    end
+  end
+end

data/lib/kiosk/server/headers_middleware.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Adds the Kiosk response headers to every response under the mount path.
+    # Install it before `ActionDispatch::ShowExceptions` so error responses
+    # are stamped too; the {Engine} does.
+    class HeadersMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      # Read before the call: ShowExceptions rewrites PATH_INFO on an error.
+      def call(env)
+        kiosk = kiosk_path?(env['PATH_INFO'])
+        status, headers, body = @app.call(env)
+        Headers.add_to(headers) if kiosk
+        [status, headers, body]
+      end
+
+      private
+
+      def kiosk_path?(path)
+        return false if path.blank?
+
+        mount = Kiosk.configuration.mount_path
+        path == mount || path.start_with?("#{mount}/")
+      end
+    end
+  end
+end

data/lib/kiosk/server/identity_resolution.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The identity of a wire or event-stream caller: the bearer token, read by
+    # the configured agent IdP or the bundled kiosk-pop one. A cookie session
+    # reaches only the human-side pages and the binding endpoints.
+    module IdentityResolution
+      module_function
+
+      def agent_idp
+        Kiosk.configuration.agent_idp || AgentIdentityProviders::DefaultAgentIdp.new
+      end
+
+      def resolve(request)
+        agent_idp.verify(request)
+      end
+    end
+  end
+end

data/lib/kiosk/server/issuer_middleware.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rack/request'
+
+module Kiosk
+  module Server
+    # Sets `Kiosk.current_issuer` for the request: its origin when the operator
+    # serves it (`c.issuer` or one of `c.additional_origins`), else `c.issuer`.
+    # The {Engine} installs it beside {HeadersMiddleware}; a plain Rack app
+    # `use`s it.
+    class IssuerMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        issuer = Kiosk.configuration.issuer_for(::Rack::Request.new(env).base_url)
+        Kiosk.with_issuer(issuer) { @app.call(env) }
+      end
+    end
+  end
+end

data/lib/kiosk/server/jwks.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The JWKS document (RFC 7517 §5) of this deployment's signing keys.
+    module Jwks
+      module_function
+
+      def build(keys:)
+        { keys: Array(keys).map(&:to_jwk) }
+      end
+    end
+  end
+end

data/lib/kiosk/server/jwt_issuer.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'securerandom'
+
+module Kiosk
+  module Server
+    # Issues and verifies the RS256 access tokens of the bundled kiosk-pop IdP.
+    module JwtIssuer
+      ALGORITHM = 'RS256'
+      DEFAULT_EXPIRES_IN = 3600
+      DEFAULT_LEEWAY = 60
+
+      # A `kid` not in the JWKS: the signature cannot be checked.
+      UNKNOWN_KID = ->(e) { e.message.include?('public key for kid') || e.message.include?('Could not find public key') }
+      private_constant :UNKNOWN_KID
+
+      class Error < StandardError; end
+      class SignatureError < Error; end
+      class ExpiredError < Error; end
+      class AudienceError < Error; end
+      class InvalidError < Error; end
+      # The agent's revocation watermark covers the token's `iat`.
+      class RevokedError < Error; end
+
+      module_function
+
+      # rubocop:disable-next Metrics/ParameterLists -- a keyword-only public API; callers pass each option by name
+      def issue(claims:, audience:, signing_key: nil, issuer: nil, expires_in: DEFAULT_EXPIRES_IN, now: Time.current)
+        signing_key ||= Kiosk.configuration.signing_key
+        issuer      ||= Kiosk.current_issuer
+        raise ArgumentError, 'issuer is required (set Kiosk.configuration.issuer or pass :issuer)' if issuer.blank?
+        raise ArgumentError, 'signing_key must carry a private key for issuance' unless signing_key.private?
+
+        payload = registered_claims(claims, issuer: issuer, audience: audience, issued_at: now.to_i, expires_in: expires_in)
+        ::JWT.encode(payload, signing_key.rsa, ALGORITHM, { kid: signing_key.kid, typ: 'JWT' })
+      end
+
+      def verify(token:, jwks:, audience: nil, issuer: nil, leeway: DEFAULT_LEEWAY)
+        claims = decode(token, normalize_jwks(jwks), audience: audience, issuer: issuer, leeway: leeway)
+        revoked = Kiosk.configuration.revocation_store.revoked?(agent_id: claims[:agent_id], iat: claims[:iat])
+        raise RevokedError, 'access token revoked' if revoked
+
+        claims
+      end
+
+      def registered_claims(claims, issuer:, audience:, issued_at:, expires_in:)
+        payload = claims.dup
+        payload[:iat] = issued_at
+        payload[:nbf] = issued_at
+        payload[:exp] = issued_at + expires_in
+        payload[:iss] = issuer
+        payload[:aud] = audience
+        payload[:jti] ||= SecureRandom.uuid
+        payload
+      end
+
+      def decode(token, jwks, audience:, issuer:, leeway:)
+        decoded, = ::JWT.decode(
+          token, nil, true,
+          jwks: jwks, algorithms: [ALGORITHM], aud: audience, iss: issuer,
+          verify_aud: !audience.nil?, verify_iss: !issuer.nil?, leeway: leeway
+        )
+        symbolize(decoded)
+      rescue ::JWT::DecodeError => e
+        raise error_class_for(e), e.message
+      end
+
+      def error_class_for(error)
+        case error
+        when ::JWT::ExpiredSignature then ExpiredError
+        when ::JWT::InvalidAudError then AudienceError
+        when ::JWT::VerificationError, ::JWT::IncorrectAlgorithm, UNKNOWN_KID then SignatureError
+        else InvalidError
+        end
+      end
+
+      def normalize_jwks(input)
+        case input
+        when Hash
+          input
+        when Array
+          { keys: input.map { |sk| sk.is_a?(SigningKey) ? sk.to_jwk : sk } }
+        when SigningKey
+          { keys: [input.to_jwk] }
+        else
+          raise ArgumentError, "jwks must be a Hash, Array, or SigningKey, got #{input.class}"
+        end
+      end
+
+      def symbolize(hash)
+        hash.each_with_object({}) { |(k, v), out| out[k.to_sym] = v }
+      end
+
+      private_class_method :registered_claims, :decode, :error_class_for
+    end
+  end
+end

data/lib/kiosk/server/kyc.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+
+module Kiosk
+  module Server
+    # The KYC module: `request_kyc`, the provider's callback, the
+    # `kyc_verification` topic and the per-person grants. The operator declares
+    # `kyc_claims` and gates with {.require!}.
+    module Kyc
+      NAME          = 'request_kyc'
+      TOPIC         = 'kyc_verification'
+      CALLBACK_PATH = 'kyc/callback'
+      MAX_OPEN      = 3
+      OPEN_WINDOW   = 15 * 60
+
+      REQUEST_HINT = "call `#{NAME}` to verify %<claims>s: subscribe to the #{TOPIC} topic first, relay the " \
+                     'verification_url it returns to your human, and retry once the event arrives'.freeze
+      ATTEST_HINT  = 'submit a KYC attestation carrying %<claims>s to POST <endpoint>/agents/kyc, then retry'
+      CLOSED_HINT  = 'verification of %<claims>s is not available at this origin and retrying will not help'
+
+      INPUT_SCHEMA = { type: 'object', additionalProperties: false, properties: {}, required: [] }.freeze
+
+      OUTPUT_SCHEMA = {
+        type: 'object', additionalProperties: false,
+        properties: {
+          request_id: { type: 'string', description: 'The id the kyc_verification event for this check carries.' },
+          verification_url: { type: 'string', description: 'The page to hand to your human.' },
+          status: { const: 'pending' }
+        },
+        required: %w[request_id verification_url status]
+      }.freeze
+
+      EVENT_SCHEMA = {
+        type: 'object', additionalProperties: false,
+        properties: {
+          request_id: { type: 'string' },
+          status: { const: 'approved' },
+          kyc_jws: { type: 'string', description: 'The signed attestation. It is already recorded here; ' \
+                                                  'you may also submit it to POST <endpoint>/agents/kyc.' }
+        },
+        required: %w[request_id status kyc_jws]
+      }.freeze
+
+      class << self
+        def provider = Kiosk.configuration.kyc_provider
+
+        def claims = Array(Kiosk.configuration.kyc_claims).map(&:to_s)
+
+        def served!
+          return if provider
+
+          raise Errors::ModuleNotServed.new(
+            'this operator does not serve the KYC module',
+            hint: 'no verification can be opened at this origin and retrying will not help — ' \
+                  'proceed as you would at an operator that offers none.'
+          )
+        end
+
+        def register!
+          claims_declared!
+          Actions.declare(NAME, method(:call), description: description,
+                                               input_schema: INPUT_SCHEMA, output_schema: OUTPUT_SCHEMA)
+          Events.register(
+            name: TOPIC, reach: :principal,
+            description: 'An identity check you opened with request_kyc was approved and recorded for ' \
+                         'your human. Retry what you were doing.',
+            payload_schema: EVENT_SCHEMA,
+            subject_reachable: ->(request_id, identity) { owner_of(request_id) == identity.user_id.to_s }
+          )
+        end
+
+        def claims_declared!
+          return unless claims.empty?
+
+          raise Errors::ConfigurationError,
+                'Kiosk::Server: kyc_provider is set but kyc_claims is empty, so no verification can grant ' \
+                'a gated action. Set: Kiosk.configure { |c| c.kyc_claims = %w[age_over_18] }'
+        end
+
+        def description
+          "Start the identity check this origin's gated actions need (#{claims.join(', ')}) for your " \
+            "human. Subscribe to the `#{TOPIC}` topic BEFORE calling this, then relay verification_url " \
+            'to your human: a KYC provider confirms those facts without passing on any document. Once ' \
+            'they approve, the event arrives and the facts are recorded; retry the gated action. At ' \
+            "most #{MAX_OPEN} checks may be open at once; one stops counting when approved, or " \
+            "#{OPEN_WINDOW / 60} minutes after it was opened. A check your human refuses sends no event."
+        end
+
+        def call(_args) = Verification.open(CurrentRequest.identity.user_id.to_s)
+
+        def callback_url
+          "#{Kiosk.current_issuer.to_s.chomp('/')}#{Kiosk.configuration.mount_path}/#{CALLBACK_PATH}"
+        end
+
+        # The provider's `POST <endpoint>/kyc/callback`.
+        def callback(body) = Verification.complete(body.transform_keys(&:to_s))
+
+        # Replaces the person's grants with the names `attributes` holds as
+        # JSON `true`.
+        delegate :grant!, to: :'Kiosk::Server::Kyc::Store'
+
+        # The gate: raises `kyc_required` unless the calling principal holds
+        # every one of `names`. `detail` replaces the default refusal text.
+        def require!(names = claims, detail: nil)
+          return if Store.granted?(CurrentRequest.identity.user_id, names.uniq)
+
+          listed = names.join(', ')
+          raise Errors::KycRequired.new(detail || "this action requires the verified attributes #{listed}",
+                                        hint: format(gate_hint, claims: listed))
+        end
+
+        private
+
+        # Names only a path this origin serves.
+        def gate_hint
+          return REQUEST_HINT if provider
+          return ATTEST_HINT if Kiosk.configuration.kyc_public_key
+
+          CLOSED_HINT
+        end
+
+        def owner_of(request_id) = Store.owner_of(request_id)
+      end
+
+      # Opens a verification at the provider and completes it from the provider's callback.
+      module Verification
+        class << self
+          def open(user_id)
+            refuse_over_cap!(user_id)
+            opened = open_verification(user_id)
+            Store.insert_request(opened.fetch(:request_id), user_id, opened.fetch(:nonce))
+            { 'request_id' => opened.fetch(:request_id), 'verification_url' => opened.fetch(:verification_url),
+              'status' => 'pending' }
+          end
+
+          def complete(body)
+            request_id = required_field(body, 'request_id')
+            kyc_jws    = required_field(body, 'kyc_jws')
+            row = matching_request(request_id, body['nonce'].to_s)
+            claims = KycVerifier.verify(raw_jws: kyc_jws, subject: row.fetch('user_id'))
+            Store.approve!(row, claims[:attributes])
+            Events.emit(topic: TOPIC, subject: request_id, identity_scope: [row.fetch('user_id')],
+                        data: { 'request_id' => request_id, 'status' => 'approved', 'kyc_jws' => kyc_jws })
+          end
+
+          private
+
+          def open_verification(user_id)
+            Kyc.provider.open_verification(subject: user_id, claims: Kyc.claims,
+                                           audience: Kiosk.configuration.kyc_audience.to_s,
+                                           callback_url: Kyc.callback_url)
+          rescue Kiosk::KycProviders::Unavailable => e
+            FailureLog.report("#{NAME} could not open a verification", e)
+            raise Errors::WireError.new(
+              'the verification service this operator uses did not open a request',
+              code: 'action_failed',
+              hint: 'nothing about your call is wrong. Try `request_kyc` again shortly.'
+            )
+          end
+
+          def refuse_over_cap!(user_id)
+            return if Store.open_count(user_id, OPEN_WINDOW) < MAX_OPEN
+
+            raise Errors::WireError.new(
+              'too many verifications are already open for this account',
+              code: 'quota_exceeded',
+              hint: "at most #{MAX_OPEN} may be open at once; one stops counting when your human " \
+                    "approves it, and in any case #{OPEN_WINDOW / 60} minutes after it was opened. " \
+                    "Wait for the #{TOPIC} event on a page you were already given."
+            )
+          end
+
+          def required_field(body, name)
+            value = body[name].to_s
+            raise Errors.missing_field(name) if value.empty?
+
+            value
+          end
+
+          # The open verification `request_id` names, if `nonce` is the one it was opened with.
+          def matching_request(request_id, nonce)
+            row = Store.open_request(request_id)
+            raise Errors::NotFound, 'no open verification has that request_id' unless row
+            raise Errors::Forbidden, "the callback's nonce does not match the verification" unless secure_equal?(row.fetch('nonce'), nonce)
+
+            row
+          end
+
+          def secure_equal?(expected, given)
+            !expected.to_s.empty? && expected.bytesize == given.bytesize &&
+              OpenSSL.fixed_length_secure_compare(expected, given)
+          end
+        end
+      end
+
+      # The `kyc_requests` and `kyc_attributes` tables.
+      module Store
+        class << self
+          def insert_request(request_id, user_id, nonce)
+            execute("INSERT INTO #{table('kyc_requests')} (id, user_id, nonce) VALUES ($1, $2, $3)",
+                    request_id, user_id, nonce)
+          end
+
+          def open_count(user_id, window)
+            execute("SELECT count(*) AS n FROM #{table('kyc_requests')} WHERE user_id = $1 " \
+                    'AND approved_at IS NULL AND created_at > now() - make_interval(secs => $2)',
+                    user_id, window).first.fetch('n').to_i
+          end
+
+          def open_request(request_id)
+            execute("SELECT id, user_id::text AS user_id, nonce FROM #{table('kyc_requests')} " \
+                    'WHERE id = $1 AND approved_at IS NULL', request_id).first
+          end
+
+          def owner_of(request_id)
+            execute("SELECT user_id::text AS user_id FROM #{table('kyc_requests')} WHERE id = $1",
+                    request_id.to_s).first&.fetch('user_id')
+          end
+
+          def approve!(row, attributes)
+            connection.transaction do
+              execute("UPDATE #{table('kyc_requests')} SET approved_at = now() WHERE id = $1", row.fetch('id'))
+              write_grants(row.fetch('user_id'), attributes)
+            end
+          end
+
+          def grant!(user_id, attributes)
+            connection.transaction { write_grants(user_id, attributes) }
+          end
+
+          # True when the person holds every one of `names`; false for none.
+          def granted?(user_id, names)
+            return false if names.empty?
+
+            quoted = names.map { |name| connection.quote(name) }.join(', ')
+            rows = execute("SELECT count(*) AS n FROM #{table('kyc_attributes')} " \
+                           "WHERE user_id = $1 AND name IN (#{quoted})", user_id.to_s)
+            rows.first.fetch('n').to_i == names.size
+          end
+
+          private
+
+          def write_grants(user_id, attributes)
+            execute("DELETE FROM #{table('kyc_attributes')} WHERE user_id = $1", user_id.to_s)
+            execute("INSERT INTO #{table('kyc_attributes')} (user_id, name) " \
+                    "SELECT $2, key FROM jsonb_each($1::jsonb) WHERE value = 'true'::jsonb",
+                    JSON.generate(attributes), user_id.to_s)
+          end
+
+          def table(name) = connection.quote_table_name("#{Kiosk.configuration.schema}.#{name}")
+
+          def execute(sql, *binds) = connection.exec_query(sql, 'Kiosk KYC', binds).to_a
+
+          def connection = ::ActiveRecord::Base.lease_connection
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/kyc_verifier.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module Kiosk
+  module Server
+    # Verifies a KYC attestation JWS against `kyc_public_key`: `iss`, `aud`,
+    # `sub` and `level: "verified"` must match, and the configured
+    # `kyc_provider` must accept it; only attributes
+    # that are literally `true` are granted.
+    module KycVerifier
+      # Named once for the decode and the published hint.
+      REQUIRED_CLAIMS = %w[exp iss aud sub].freeze
+      SIGNATURE_HINT  = 'an attestation is a compact RS256 JWS signed by the issuer this origin ' \
+                        'is configured to trust'
+      SUBJECT_HINT    = "sub must name the principal: the caller's at POST <endpoint>/agents/kyc, " \
+                        "the open verification's at the callback"
+
+      module_function
+
+      def verify(raw_jws:, subject:)
+        config  = Kiosk.configuration
+        payload = decode(raw_jws, config)
+        check_issuer!(payload, config)
+        # Binds the attestation to this operator.
+        if payload[:aud].to_s != config.kyc_audience.to_s
+          raise Errors::Forbidden.new('KYC attestation audience mismatch',
+                                      hint: audience_hint(payload, config))
+        end
+
+        check_subject!(payload, subject)
+        check_provider!(payload, config)
+
+        payload.merge(attributes: verified_attributes(payload[:attributes]))
+      end
+
+      # The names granted as literal `true`; `{}` when absent; a non-object
+      # is refused.
+      def verified_attributes(raw)
+        return {} if raw.nil?
+
+        raise Errors::Forbidden, 'KYC attestation attributes must be an object of {name: true} booleans' unless raw.is_a?(Hash)
+
+        raw.each_with_object({}) do |(name, value), acc|
+          acc[name.to_s] = true if value == true
+        end
+      end
+
+      # The verified payload with symbol keys.
+      def decode(raw_jws, config)
+        payload, = ::JWT.decode(raw_jws, public_key!(config), true,
+                                algorithms: ['RS256'], verify_expiration: true, required_claims: REQUIRED_CLAIMS)
+        payload.transform_keys(&:to_sym)
+      rescue ::JWT::ExpiredSignature
+        raise Errors::Forbidden, 'KYC attestation expired'
+      rescue ::JWT::MissingRequiredClaim
+        raise Errors::Forbidden.new('KYC attestation missing a required claim', hint: "an attestation carries #{REQUIRED_CLAIMS.join(', ')}")
+      rescue ::JWT::DecodeError
+        raise Errors::Forbidden.new('KYC attestation signature invalid', hint: SIGNATURE_HINT)
+      end
+
+      # Refused when this origin trusts no KYC issuer.
+      def public_key!(config)
+        key = config.kyc_public_key
+        return key unless key.nil?
+
+        raise Errors::ModuleNotServed.new(
+          'this operator does not serve the KYC module',
+          hint: 'no KYC attestation is accepted at this origin; retrying will not help. ' \
+                'An operator that means to serve KYC sets Kiosk.configuration.kyc_public_key.'
+        )
+      end
+
+      def check_issuer!(payload, config)
+        return if payload[:iss] == config.kyc_issuer
+
+        raise Errors::Forbidden.new(
+          'KYC attestation issuer mismatch',
+          hint: "expected #{config.kyc_issuer.inspect}, got #{payload[:iss].inspect}"
+        )
+      end
+
+      def audience_hint(payload, config)
+        "aud must equal this operator's kyc_audience " \
+          "(expected #{config.kyc_audience.inspect}, got #{payload[:aud].inspect})"
+      end
+
+      # Subject and level. A bigint-PK host's subject is an Integer.
+      def check_subject!(payload, subject)
+        raise Errors::Forbidden.new('KYC attestation subject mismatch', hint: SUBJECT_HINT) unless payload[:sub].to_s == subject.to_s
+
+        raise Errors::Forbidden, 'kyc level not verified' unless payload[:level] == 'verified'
+      end
+
+      # The provider's own checks ({Kiosk::KycProviders::Base#accepts?}).
+      def check_provider!(payload, config)
+        provider = config.kyc_provider
+        return if provider.nil? || provider.accepts?(payload.transform_keys(&:to_s))
+
+        raise Errors::Forbidden, 'the KYC provider does not accept this attestation at this operator'
+      end
+
+      private_class_method :decode, :public_key!, :check_issuer!, :audience_hint, :check_subject!, :check_provider!
+    end
+  end
+end