kiosk-server 0.5.20 → 0.6.1

data/lib/kiosk/server/mandate_verifier.rb

@@ -1,213 +1,171 @@
 # frozen_string_literal: true
 
-require 'jwt'
-
 module Kiosk
   module Server
-    # Verifies the agent-signed AP2 mandate chain (intent → cart → payment):
-    # signed by the authenticated agent's key, issued for this origin, bound to
-    # the authenticated principal, and within the intent's cap.
+    # Verifies the two closed AP2 v0.2 mandates of a `pay`. Each is an SD-JWT
+    # signed with the authenticated agent's key. The checkout mandate binds a
+    # checkout this origin signed for this account; the payment mandate pays
+    # exactly that checkout, to this origin.
     module MandateVerifier
       # §11.1: an ISO 4217 alpha-3 code, matched after {canonical_currency}.
       CURRENCY_CODE = /\A[a-z]{3}\z/
 
-      REQUIRED_CLAIMS = %w[id user_id agent_id iss iat exp].freeze
+      CHECKOUT_VCT = 'mandate.checkout.1'
+      PAYMENT_VCT  = 'mandate.payment.1'
+      TYP          = 'dc+sd-jwt'
 
       # Longer than this counts as non-expiring, which the spec refuses.
       MAX_MANDATE_LIFETIME_SECONDS = 24 * 60 * 60
 
       module_function
 
-      def verify_intent(raw_jws:, identity:)
-        payload = Token.decode_and_check(raw_jws, identity)
-        require_amount!(payload, :cap_amount_cents)
-        currency = require_currency!(payload)
-
-        Kiosk::Mandate::IntentMandate.new(
-          **Token.common(payload, raw_jws),
-          scope: payload[:scope], cap_amount_cents: payload[:cap_amount_cents], currency: currency
+      def verify_checkout(sd_jwt:, identity:)
+        content = Token.content(sd_jwt, identity, CHECKOUT_VCT)
+        checkout_jwt, checkout_hash = Binding.checkout_jwt!(content)
+        checkout = Checkout.verify(checkout_jwt, identity: identity)
+        Kiosk::Mandate::CheckoutMandate.new(
+          **Token.common(sd_jwt, content, identity),
+          checkout_hash: checkout_hash,
+          line_items: checkout['line_items'],
+          total_amount_cents: checkout['total_amount_cents'],
+          currency: canonical_currency(checkout['currency'])
         )
       end
 
-      # `payment_method` is optional: the PSP charges the principal's card on file.
-      def verify_payment(raw_jws:, identity:, cart:)
-        payload = Token.decode_and_check(raw_jws, identity)
-        require_amount!(payload, :amount_cents)
-        currency = require_currency!(payload)
-        Binding.payment_to_cart!(payload, currency, cart)
+      def verify_payment(sd_jwt:, identity:, checkout:)
+        content = Token.content(sd_jwt, identity, PAYMENT_VCT)
+        Binding.payment_to_checkout!(content, checkout)
+        instrument = Binding.instrument!(content['payment_instrument'])
 
         Kiosk::Mandate::PaymentMandate.new(
-          **Token.common(payload, raw_jws),
-          cart_mandate_id: payload[:cart_mandate_id], payment_method: payload[:payment_method],
-          amount_cents: payload[:amount_cents], currency: currency
-        )
-      end
-
-      def verify_cart(raw_jws:, identity:, intent:)
-        payload = Token.decode_and_check(raw_jws, identity)
-        require_amount!(payload, :total_amount_cents)
-        currency = require_currency!(payload)
-        require_line_items!(payload)
-
-        fields = Token.claims(payload, :intent_mandate_id, :line_items, :total_amount_cents)
-        cart = Kiosk::Mandate::CartMandate.new(**Token.common(payload, raw_jws), **fields, currency: currency)
-        Binding.cart_to_intent!(cart, intent)
-        cart
-      end
-
-      # Before any `.to_i`: nil, zero or negative would launder the cap.
-      def require_amount!(payload, field)
-        value = payload[field]
-        raise Errors::Forbidden.new("mandate missing required amount field: #{field}", hint: "#{field} is a required AP2 mandate field") if value.nil?
-        return if value.is_a?(Integer) && value.positive?
-
-        raise Errors::Forbidden.new(
-          "mandate #{field} must be a positive integer number of cents",
-          hint: "#{field} was #{value.inspect}"
-        )
-      end
-
-      # §11.2: at least one entry; the settlement is reconciled from it.
-      def require_line_items!(payload)
-        value = payload[:line_items]
-        raise Errors::Forbidden.new('mandate missing required line_items field', hint: LINE_ITEMS_HINT) if value.nil?
-        raise Errors::Forbidden.new('mandate line_items must be an array', hint: "line_items was #{value.class}") unless value.is_a?(Array)
-        return unless value.empty?
-
-        raise Errors::Forbidden.new(
-          'mandate line_items must not be empty',
-          hint: 'a cart mandate says WHAT is being bought and the settlement is reconciled ' \
-                'from it — an empty array withholds both while a positive total is charged'
-        )
-      end
-
-      LINE_ITEMS_HINT = 'line_items is a required AP2 cart-mandate field — the settlement trail ' \
-                        'is reconciled from it'
-
-      # §11.1: refuses a non-String, blank or non-alpha-3 currency and returns
-      # the canonical form, so the spending-cap tally has one key per currency.
-      def require_currency!(payload)
-        value = payload[:currency]
-        raise Errors::Forbidden.new('mandate missing required currency field', hint: 'currency is a required AP2 mandate field') if value.nil?
-        raise Errors::Forbidden.new('mandate currency must be a non-empty string', hint: blank_currency_hint(value)) unless value.is_a?(String) && !value.strip.empty?
-
-        code = canonical_currency(value)
-        return code if CURRENCY_CODE.match?(code)
-
-        raise Errors::Forbidden.new(
-          'mandate currency is not an ISO 4217 alpha-3 code',
-          hint: "currency was #{value.inspect} — send a three-letter currency code, such as \"eur\""
+          **Token.common(sd_jwt, content, identity), transaction_id: content['transaction_id'],
+                                                     payment_instrument: instrument, amount_cents: checkout.total_amount_cents, currency: checkout.currency
         )
       end
 
-      def blank_currency_hint(value)
-        "currency was #{value.inspect} — send the three-letter currency code of this mandate, such as \"eur\""
-      end
+      CHECKOUT_HINT = 'a checkout mandate carries the checkout_jwt the operator answered, unchanged, and ' \
+                      'checkout_hash: the base64url SHA-256 of that string'
 
       # Public: an operator reading `settlements.currency` needs the same lower-casing.
       def canonical_currency(value)
         value.to_s.downcase
       end
-      private_class_method :require_amount!, :blank_currency_hint
 
-      # How each mandate in the chain must agree with the one it follows.
+      # How the payment mandate must agree with the checkout it pays.
       module Binding
         module_function
 
-        def payment_to_cart!(payload, currency, cart)
-          raise Errors::Forbidden, 'payment not bound to the cart' unless payload[:cart_mandate_id] == cart.id
-          return if payload[:amount_cents].to_i == cart.total_amount_cents.to_i && currency == cart.currency
+        # @return [Array(String, String)] the checkout_jwt and its hash
+        def checkout_jwt!(content)
+          checkout_jwt = content['checkout_jwt']
+          raise Errors::Forbidden.new('checkout mandate has no checkout_jwt', hint: CHECKOUT_HINT) unless checkout_jwt.is_a?(String)
+
+          checkout_hash = SdJwt.digest(checkout_jwt)
+          return [checkout_jwt, checkout_hash] if content['checkout_hash'] == checkout_hash
+
+          raise Errors::Forbidden.new('checkout_hash is not the hash of checkout_jwt', hint: CHECKOUT_HINT)
+        end
+
+        def payment_to_checkout!(content, checkout)
+          raise Errors::Forbidden.new('payment not bound to the checkout', hint: 'transaction_id is the checkout_hash of the checkout mandate') unless content['transaction_id'] == checkout.checkout_hash
 
-          raise Errors::Forbidden, 'payment amount/currency does not match cart'
+          payee!(content['payee'])
+          amount!(content['payment_amount'], checkout)
         end
 
-        def cart_to_intent!(cart, intent)
-          unless cart.intent_mandate_id == intent.id
-            raise Errors::Forbidden.new('cart not bound to the intent',
-                                        hint: "expected intent_mandate_id #{intent.id.inspect}")
-          end
-          cart_currency!(cart, intent)
-          cart_cap!(cart, intent)
+        def payee!(payee)
+          issuer = Kiosk.current_issuer
+          return if payee.is_a?(Hash) && payee['id'] == issuer
+
+          raise Errors::Forbidden.new('payment payee is not this origin', hint: "payee is the checkout's merchant, whose id is #{issuer.inspect}")
         end
 
-        # A cap is meaningless across currencies.
-        def cart_currency!(cart, intent)
-          return if cart.currency == intent.currency
+        # The signed amount must be the checkout's, in its currency, compared as a code.
+        def amount!(amount, checkout)
+          return if amount.is_a?(Hash) && amount['amount'] == checkout.total_amount_cents &&
+                    amount['currency'].is_a?(String) && MandateVerifier.canonical_currency(amount['currency']) == checkout.currency
 
-          raise Errors::Forbidden.new('cart currency does not match intent cap currency',
-                                      hint: "cart #{cart.currency.inspect} != intent #{intent.currency.inspect}")
+          raise Errors::Forbidden.new('payment amount/currency does not match the checkout',
+                                      hint: "payment_amount is {amount: #{checkout.total_amount_cents}, currency: #{checkout.currency.inspect}}")
         end
 
-        def cart_cap!(cart, intent)
-          return unless cart.total_amount_cents.to_i > intent.cap_amount_cents.to_i
+        # @return [String] the instrument id: a PSP payment-method id, or `on_file`
+        def instrument!(instrument)
+          return instrument['id'] if instrument.is_a?(Hash) && [instrument['id'], instrument['type']].all? { it.is_a?(String) && !it.empty? }
 
-          raise Errors::Forbidden.new('cart total exceeds intent cap',
-                                      hint: "cart #{cart.total_amount_cents} > cap #{intent.cap_amount_cents}")
+          raise Errors::Forbidden.new('payment mandate has no payment_instrument',
+                                      hint: 'payment_instrument is {id, type}; {"id": "on_file", "type": "card"} pays with the saved card')
         end
       end
 
-      # The signed JWS: its signature, issuer, principal and lifetime.
+      # The SD-JWT: its signature, its type and its lifetime.
       module Token
         module_function
 
-        # The attributes every mandate carries.
-        def common(payload, raw_jws)
-          { id: payload[:id], user_id: payload[:user_id], agent_id: payload[:agent_id], issuer: payload[:iss],
-            expires_at: Time.at(payload[:exp]).utc, created_at: Time.at(payload[:iat]).utc, raw_jws: raw_jws }
+        # The attributes both mandates carry.
+        def common(sd_jwt, content, identity)
+          { reference: SdJwt.digest(sd_jwt), user_id: identity.user_id, agent_id: identity.agent_id,
+            issuer: Kiosk.current_issuer, expires_at: Time.at(content['exp']).utc, sd_jwt: sd_jwt }
         end
 
-        # The named claims, nil when absent.
-        def claims(payload, *names) = names.index_with { |name| payload[name] }
+        # The one mandate in `delegate_payload`, with every disclosure in place.
+        def content(sd_jwt, identity, vct)
+          payload = decode(sd_jwt, identity)
+          content = payload['delegate_payload']
+          content = content.first if content.is_a?(Array) && content.one?
+          raise Errors::Forbidden.new('mandate carries no mandate', hint: SHAPE_HINT) unless content.is_a?(Hash)
+          raise Errors::Forbidden.new("mandate vct is not #{vct}", hint: VCT_HINT) unless content['vct'] == vct
 
-        def decode_and_check(raw_jws, identity)
-          payload = decode(raw_jws, identity)
-          check_principal!(payload, identity)
-          require_numeric_timestamp!(payload, :iat)
-          require_numeric_timestamp!(payload, :exp)
-          enforce_max_lifetime!(payload)
-          payload
+          check_lifetime!(content)
+          content
         end
 
-        def decode(raw_jws, identity)
-          payload, = ::JWT.decode(raw_jws, payment_key(identity), true, algorithms: ['RS256'], required_claims: REQUIRED_CLAIMS)
-          payload.transform_keys(&:to_sym)
-        rescue ::JWT::ExpiredSignature
-          raise Errors::Forbidden, 'mandate expired'
-        rescue ::JWT::MissingRequiredClaim
-          raise Errors::Forbidden.new('mandate missing a required claim', hint: "a mandate carries #{REQUIRED_CLAIMS.join(', ')}")
+        SHAPE_HINT = 'the signed payload is {"_sd_alg": "sha-256", "delegate_payload": [{"...": <digest>}]}, ' \
+                     'and the one disclosure is the mandate'
+        VCT_HINT   = "send closed mandates: #{CHECKOUT_VCT} and #{PAYMENT_VCT}. This operator takes no open mandate".freeze
+
+        def decode(sd_jwt, identity)
+          key = payment_key(identity)
+          algorithm = AssistantKey.algorithm(key)
+          payload, header = SdJwt.verify(sd_jwt, key:, algorithm:)
+          return payload if header['typ'] == TYP
+
+          raise Errors::Forbidden.new("mandate typ is not #{TYP}", hint: "the JWT header is {\"alg\": \"#{algorithm}\", \"typ\": \"#{TYP}\"}")
+        rescue SdJwt::Invalid => e
+          raise Errors::Forbidden.new('mandate is not a valid SD-JWT', hint: e.message)
         rescue ::JWT::DecodeError
-          raise Errors::Forbidden.new('mandate signature invalid', hint: "a mandate is a compact RS256 JWS signed with the agent's payment key")
+          raise Errors::Forbidden.new('mandate signature invalid',
+                                      hint: "a mandate is an SD-JWT that the agent's registered key signs (#{AssistantKey.algorithms.join(' or ')})")
         end
 
         def payment_key(identity)
           AgentIdentityProviders::DefaultAgentIdp.new.agent_payment_key(identity.agent_id)
-        rescue Kiosk::AgentIdentityProviders::InvalidToken
+        rescue Kiosk::AgentIdentityProviders::InvalidToken, Errors::BadRequest
           # The agent was revoked between authentication and now.
           raise Errors::Forbidden.new('mandate agent has no registered payment key', hint: 'the authenticated agent is revoked or unknown')
         end
 
-        def check_principal!(payload, identity)
-          issuer = Kiosk.current_issuer
-          raise Errors::Forbidden.new('mandate issuer mismatch', hint: "expected #{issuer.inspect}") if payload[:iss] != issuer
-          # As strings: a bigint-PK host's identity carries an Integer.
-          return if payload[:agent_id].to_s == identity.agent_id.to_s && payload[:user_id].to_s == identity.user_id.to_s
+        def check_lifetime!(content)
+          require_numeric_timestamp!(content, 'iat')
+          require_numeric_timestamp!(content, 'exp')
+          raise Errors::Forbidden, 'mandate expired' if content['exp'] <= Time.now.to_i
 
-          raise Errors::Forbidden.new('mandate principal mismatch', hint: 'mandate must be signed for the authenticated agent/user')
+          enforce_max_lifetime!(content)
         end
 
         # Before `Time.at`, which raises on a String.
-        def require_numeric_timestamp!(payload, field)
-          return if payload[field].is_a?(Numeric)
+        def require_numeric_timestamp!(content, field)
+          return if content[field].is_a?(Integer)
 
           raise Errors::BadRequest.new(
             "mandate #{field} must be an integer Unix timestamp",
-            hint: "#{field} was #{payload[field].class} — send #{field} as a NumericDate integer"
+            hint: "#{field} was #{content[field].class} — send #{field} as a NumericDate integer"
           )
         end
 
         # exp − now, not exp − iat, so a future-dated iat cannot stretch it.
-        def enforce_max_lifetime!(payload)
-          return if payload[:exp].to_i - Time.now.to_i <= MAX_MANDATE_LIFETIME_SECONDS
+        def enforce_max_lifetime!(content)
+          return if content['exp'] - Time.now.to_i <= MAX_MANDATE_LIFETIME_SECONDS
 
           raise Errors::BadRequest.new(
             "mandate lifetime exceeds the maximum of #{MAX_MANDATE_LIFETIME_SECONDS}s",

data/lib/kiosk/server/oauth_answers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The answers of the `/oauth/*` endpoints: JSON that no cache keeps
+    # (RFC 6749 Section 5.1), and `{error, error_description}` for a refusal.
+    module OauthAnswers
+      private
+
+      def render_oauth(body, status: :ok)
+        Headers.add_to(response.headers)
+        response.set_header('Cache-Control', 'no-store')
+        render json: body, status: status
+      end
+
+      def render_oauth_error(error)
+        render_oauth(error.to_h, status: error.status)
+      end
+
+      # The client that the request's client assertion authenticates.
+      # @raise [OauthError] `invalid_client`
+      def authenticate_client!
+        ClientAssertion.authenticate!(params[:client_assertion_type].to_s, params[:client_assertion].to_s,
+                                      client_id: params[:client_id].presence)
+      rescue ClientAssertion::Refused => e
+        raise e.to_oauth
+      end
+    end
+  end
+end

data/lib/kiosk/server/oauth_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # A refusal on an `/oauth/*` endpoint, answered as `{error, error_description}`
+    # (RFC 6749 Section 5.2, RFC 7591 Section 3.2.2), never as a problem document.
+    class OauthError < StandardError
+      # The token and device-authorization codes, and the registration code.
+      CODES = %w[
+        invalid_request invalid_client invalid_grant unsupported_grant_type invalid_dpop_proof
+        authorization_pending slow_down expired_token access_denied
+        invalid_client_metadata
+      ].freeze
+
+      attr_reader :code
+
+      def initialize(code, description)
+        @code = code.to_s
+        raise ArgumentError, "#{@code} is not an OAuth error code of this origin" unless CODES.include?(@code)
+
+        super(description)
+      end
+
+      # RFC 6749 Section 5.2: only a failed client authentication is a 401.
+      def status = code == 'invalid_client' ? 401 : 400
+
+      def to_h = { error: code, error_description: message }
+    end
+  end
+end

data/lib/kiosk/server/open_api.rb

@@ -76,7 +76,7 @@ module Kiosk
           info: info(config),
           externalDocs: EXTERNAL_DOCS,
           servers: [{ url: endpoint, description: "This origin's Kiosk endpoint." }],
-          security: [{ bearerAuth: [] }],
+          security: [{ dpopAuth: [] }],
           tags: TAGS,
           paths: paths,
           components: Wire.components(schemas)
@@ -289,8 +289,8 @@ module Kiosk
                              'PUBLIC: no credential is required. The MODULE set this origin ' \
                              'serves is `capabilities` in /.well-known/kiosk.json.'
 
-        PAY_DESCRIPTION = 'Settle an AP2 cart: submit the signed intent -> cart -> payment ' \
-                          'mandate chain. Answers 402 `payment_setup_required` when the ' \
+        PAY_DESCRIPTION = "Pay an operator's checkout: submit the closed AP2 checkout and " \
+                          'payment mandates. Answers 402 `payment_setup_required` when the ' \
                           'identity has no card on file and 402 `payment_failed` when the ' \
                           "charge did not settle — branch on the problem document's `code`."
 
@@ -311,7 +311,7 @@ module Kiosk
 
         def components(schemas)
           {
-            securitySchemes: { bearerAuth: Parameters::BEARER_SCHEME },
+            securitySchemes: { dpopAuth: Parameters::DPOP_SCHEME },
             parameters: Parameters::RESERVED_PARAMETERS,
             headers: Parameters::PAGINATION_HEADERS,
             responses: problem_responses,
@@ -324,7 +324,7 @@ module Kiosk
             operationId: 'schema',
             tags: ['wire'],
             description: SCHEMA_DESCRIPTION,
-            # Public: opts out of the global `bearerAuth`.
+            # Public: opts out of the global `dpopAuth`.
             security: [],
             responses: ok_responses('The catalog.', 'schema.response')
           }
@@ -452,36 +452,38 @@ module Kiosk
 
         PAY = {
           'pay.request' => {
-            type: 'object', title: 'The AP2 mandate chain',
-            properties: %w[intent cart payment].to_h do |what|
-              [:"#{what}_mandate_jws", { type: 'string', description: "Compact RS256 JWS: the signed #{what} mandate." }]
+            type: 'object', title: 'The two closed AP2 mandates',
+            properties: %w[checkout payment].to_h do |what|
+              [:"#{what}_mandate", { type: 'string', description: "Compact SD-JWT: the closed AP2 #{what} mandate." }]
             end,
-            required: %w[intent_mandate_jws cart_mandate_jws payment_mandate_jws],
+            required: %w[checkout_mandate payment_mandate],
             additionalProperties: false
           },
           'pay.response' => {
-            type: 'object', title: 'Settlement receipt',
+            type: 'object', title: 'Settlement and its AP2 receipts',
             properties: {
               settlement_id: { type: 'string', description: "This origin's settlement row id." },
               psp_reference: { type: 'string', description: "The processor's own reference." },
               settled_amount_cents: { type: 'integer' },
-              currency: { type: 'string' }
+              currency: { type: 'string' },
+              **%w[checkout payment].to_h { [:"#{it}_receipt", { type: 'string', description: "The AP2 #{it} receipt: a JWT this origin signs EdDSA." }] }
             },
-            required: %w[settlement_id psp_reference settled_amount_cents currency],
+            required: %w[settlement_id psp_reference settled_amount_cents currency checkout_receipt payment_receipt],
             additionalProperties: false
           }
         }.freeze
       end
 
-      # The reserved query parameters, the shared response headers and the bearer scheme.
+      # The reserved query parameters, the shared response headers and the DPoP scheme.
       module Parameters
-        BEARER_SCHEME = {
+        DPOP_SCHEME = {
           type: 'http',
-          scheme: 'bearer',
-          bearerFormat: 'JWT',
-          description: 'An access token from the kiosk-pop auth plane ' \
-                       '(`POST <endpoint>/auth/register` or `/auth/login`), ' \
-                       'verifiable against `<endpoint>/.well-known/jwks.json`.'
+          scheme: 'DPoP',
+          description: 'An access token from the token endpoint ' \
+                       '(`POST <endpoint>/oauth/token`), ' \
+                       'verifiable against `<endpoint>/.well-known/jwks.json` and bound to the ' \
+                       'registered key: send it as `Authorization: DPoP <token>` with a `DPoP` ' \
+                       'proof header that the key signs (RFC 9449).'
         }.freeze
 
         # §8.4. OAS 3.1 §4.8.21.1: a Header Object carries no `name` or `in`.
@@ -509,7 +511,7 @@ module Kiosk
         CHALLENGE_HEADERS = {
           'WWW-Authenticate' => {
             description: '`Kiosk-PoW realm="<issuer>"` for a proof-of-work toll, ' \
-                         '`Payment realm="<issuer>", method="ap2"` for payment setup.',
+                         '`Kiosk-Payment-Setup realm="<issuer>"` for payment setup.',
             schema: { type: 'string' }
           }
         }.freeze