kiosk-server 0.5.20 → 0.6.28

data/lib/kiosk/server/executor.rb

@@ -4,7 +4,7 @@ module Kiosk
   module Server
     # Runs one call for an identity inside a {SessionContext}; returns a {Result} or raises {Errors::Base}.
     class Executor
-      # The coarse kinds of call shared by the toll, the policy and this dispatcher; not wire paths.
+      # The coarse kinds of call shared by the toll, the policy and this dispatcher; not HTTP paths.
       VERBS = %i[query run pay].freeze
 
       # Kinds with an irreversible external effect (a PSP capture) that manage their own transactions.
@@ -121,7 +121,7 @@ module Kiosk
         result
       end
 
-      # The handler's message goes to the operator's log, never onto the wire.
+      # The handler's message goes to the operator's log, never onto the protocol.
       def report_handler_failure(kind, name, error)
         FailureLog.report("#{kind} #{name.inspect} raised #{error.class}", error)
       end
@@ -134,22 +134,22 @@ module Kiosk
         end
       end
 
-      # The `pay` verb: settles an AP2 cart. The PSP capture runs outside any transaction,
-      # between phases 1 and 3 (§11.6).
+      # The `pay` verb: settles an operator-signed checkout through two closed AP2
+      # mandates. The PSP capture runs outside any transaction, between phases 1 and 3 (§11.6).
       module Pay
         RETRYABLE_HINT = 'the charge did not go through and no money moved. The human may need to ' \
-                         'update the payment method (payment_setup). Then sign a new chain and pay again.'
+                         'update the payment method (payment_setup). Then sign new mandates and pay again.'
         UNKNOWN_HINT   = 'the payment provider did not confirm the charge, so its status is unknown. ' \
-                         'Send the SAME chain again, byte for byte: this operator charges one chain at ' \
-                         'most once. Do not sign a new chain.'
-        CONFLICT_HINT  = 'this operator will not charge this chain: an earlier call with it was declined, ' \
-                         'or these mandate ids came before with other content. Before you sign a new ' \
-                         "chain, read the order's paid state through the operator's own query, and sign " \
-                         'a new chain only on a clear "not paid".'
-
-        # The verified mandates, the cart row they were persisted under, and
+                         'Send the SAME two mandates again, byte for byte: this operator charges one pair ' \
+                         'at most once. Do not sign new mandates.'
+        CONFLICT_HINT  = 'this operator will not charge these mandates: an earlier call with them was ' \
+                         'declined, or another pair for this checkout is settled or still in progress. ' \
+                         "Before you sign new mandates, read the order's paid state through the operator's " \
+                         'own query, and sign new ones only on a clear "not paid".'
+
+        # The verified mandates, the checkout row they were persisted under, and
         # whether an earlier call already persisted them.
-        Chain = Struct.new(:intent, :cart, :payment, :cart_row, :repeat)
+        Chain = Struct.new(:checkout, :payment, :checkout_row, :repeat)
 
         private
 
@@ -158,7 +158,7 @@ module Kiosk
           # Whether this origin serves payments is answered before any argument is read.
           provider = payment_provider!
           raws = pay_mandates!(args)
-          # Refused before phase 1 so the mandate ids are not burned on a charge that cannot succeed.
+          # Refused before phase 1, so the checkout is not held by a charge that cannot succeed.
           raise Errors::PaymentSetupRequired if provider.respond_to?(:setup_required?) && provider.setup_required?(user_id: identity.user_id)
 
           chain = persist_chain(raws)
@@ -177,20 +177,21 @@ module Kiosk
           )
         end
 
-        # The three signed mandates from the args, by part.
+        # The two signed mandates from the args, by part.
         def pay_mandates!(args)
           # Mandates are agent-signed, so a principal without an agent id cannot pay.
           raise Errors::Forbidden, 'payment requires an agent identity (mandates are agent-signed)' if identity.agent_id.nil?
 
-          %i[intent cart payment].to_h do |part|
-            raw = args[:"#{part}_mandate_jws"]
-            raise Errors::BadRequest, "args.#{part}_mandate_jws required" if raw.nil? || raw.to_s.empty?
+          %i[checkout payment].to_h do |part|
+            raw = args[:"#{part}_mandate"]
+            raise Errors::BadRequest, "args.#{part}_mandate required" if raw.nil? || raw.to_s.empty?
 
             [part, raw]
           end
         end
 
-        # Phase 1: verify and persist the mandate chain. A unique violation means the chain was presented before.
+        # Phase 1: verify and persist the mandates. A unique violation means they, or another
+        # live pair for the same checkout, were presented before.
         def persist_chain(raws)
           chain = Chain.new
           verify_and_persist(chain, raws)
@@ -202,30 +203,24 @@ module Kiosk
 
         def verify_and_persist(chain, raws)
           SessionContext.open(connection: connection, identity: identity) do
-            cart = verify_intent_and_cart(chain, raws)
-            # Before any persist or capture, so a refusal burns nothing.
-            enforce_spending_cap!(cart)
-            chain.payment  = MandateVerifier.verify_payment(raw_jws: raws[:payment], identity: identity, cart: cart)
-            chain.cart_row = persist_mandates(chain)
+            chain.checkout = MandateVerifier.verify_checkout(sd_jwt: raws[:checkout], identity: identity)
+            # Before any persist or capture, so a refusal holds nothing.
+            enforce_spending_cap!(chain.checkout)
+            chain.payment      = MandateVerifier.verify_payment(sd_jwt: raws[:payment], identity: identity, checkout: chain.checkout)
+            chain.checkout_row = persist_mandates(chain)
           end
           chain
         end
 
-        def verify_intent_and_cart(chain, raws)
-          chain.intent = MandateVerifier.verify_intent(raw_jws: raws[:intent], identity: identity)
-          chain.cart   = MandateVerifier.verify_cart(raw_jws: raws[:cart], identity: identity, intent: chain.intent)
-        end
-
-        # The cart row id.
+        # The checkout row id.
         def persist_mandates(chain)
-          intent_row = persist_intent_mandate(chain.intent)
-          cart_row   = persist_cart_mandate(chain.cart, intent_row_id: intent_row)
-          persist_payment_mandate(cart_row_id: cart_row, payment: chain.payment)
-          cart_row
+          checkout_row = persist_checkout_mandate(chain.checkout)
+          persist_payment_mandate(checkout_row_id: checkout_row, payment: chain.payment)
+          checkout_row
         end
 
         # Phase 2: the irreversible capture. A refusal under which no money moved
-        # declines the cart, so it stops counting against the spending cap.
+        # declines the checkout mandate, so a new pair can pay that checkout.
         def capture(provider, chain)
           charge(provider, chain)
         rescue Kiosk::PaymentProviders::SetupRequired
@@ -239,139 +234,125 @@ module Kiosk
           raise
         end
 
-        # A repeated chain resumes its capture under the same idempotency key.
+        # A repeated pair resumes its capture under the same idempotency key.
         def charge(provider, chain)
           method = chain.repeat ? :resume : :capture
-          provider.public_send(method, chain.cart, payment_method: chain.payment.payment_method)
+          provider.public_send(method, chain.checkout, payment_method: chain.payment.payment_instrument)
         end
 
         # Phase 3: record the settlement, then tell the provider, so the
         # operator's work after the payment reads the settlement. A concurrent
-        # call that settled the same cart first answers with its settlement.
+        # call that settled the same checkout first answers with its settlement.
         def settle(provider, chain, settled)
           settlement_id = record_settlement(chain, settled)
-          provider.settled(chain.cart) if provider.respond_to?(:settled)
-          settlement_result(settlement_id, settled[:psp_reference], settled[:settled_amount_cents], chain.cart.currency)
+          provider.settled(chain.checkout) if provider.respond_to?(:settled)
+          settlement_result(chain, settlement_id, settled, chain.checkout.currency)
         rescue StandardError => e
           row = unique_violation?(e) && recorded_chain(chain)
           raise unless row && row['settlement_id']
 
-          stored_settlement(row)
+          stored_settlement(chain, row)
         end
 
         # The settlement row's id.
         def record_settlement(chain, settled)
           SessionContext.open(connection: connection, identity: identity) do
-            persist_settlement(cart_row_id: chain.cart_row, cart: chain.cart, settled: settled)
+            persist_settlement(checkout_row_id: chain.checkout_row, checkout: chain.checkout, settled: settled)
           end
         end
 
-        def settlement_result(settlement_id, psp_reference, settled_amount_cents, currency)
-          Result.new(kind: :value, payload: { settlement_id:, psp_reference:, settled_amount_cents:, currency: })
+        # The settlement, and the two receipts that name its mandates (§11.3).
+        # `settled`: `psp_reference`, `settled_amount_cents` and `network_confirmation_id`.
+        def settlement_result(chain, settlement_id, settled, currency)
+          psp_reference = settled[:psp_reference]
+          receipts = Receipts.issue(checkout: chain.checkout, payment: chain.payment, settlement_id:, psp_reference:,
+                                    network_confirmation_id: settled[:network_confirmation_id])
+          Result.new(kind: :value, payload: { settlement_id:, psp_reference:, settled_amount_cents: settled[:settled_amount_cents],
+                                              currency:, **receipts })
         end
       end
 
       # The mandate and settlement rows. Every value is a bind parameter; only the
       # operator-set schema name is interpolated.
       module Ledger
-        # Byte-identical chain, scoped to the acting principal on every mandate row, with its settlement if any.
+        # The byte-identical pair of the acting principal, with its settlement if any.
         CHAIN_SQL = <<~SQL.squish
-          SELECT c.id AS cart_row, c.declined_at,
-                 s.id AS settlement_id, s.psp_reference, s.settled_amount_cents, s.currency
-          FROM %<schema>s.cart_mandates c
-          JOIN %<schema>s.intent_mandates  i ON i.id = c.intent_mandate_id
-          JOIN %<schema>s.payment_mandates p ON p.cart_mandate_id = c.id
-          LEFT JOIN %<schema>s.settlements s ON s.cart_mandate_id = c.id
-          WHERE c.user_id = $1 AND i.user_id = $1 AND p.user_id = $1
-            AND c.mandate_id = $2
-            AND c.raw_jws = $3
-            AND i.raw_jws = $4
-            AND p.raw_jws = $5
+          SELECT c.id AS checkout_row, c.declined_at,
+                 s.id AS settlement_id, s.psp_reference, s.settled_amount_cents, s.currency,
+                 s.network_confirmation_id
+          FROM %<schema>s.kiosk_checkout_mandates c
+          JOIN %<schema>s.kiosk_payment_mandates p ON p.checkout_mandate_id = c.id
+          LEFT JOIN %<schema>s.kiosk_settlements s ON s.checkout_mandate_id = c.id
+          WHERE c.user_id = $1 AND p.user_id = $1
+            AND c.reference = $2
+            AND c.sd_jwt = $3
+            AND p.sd_jwt = $4
           LIMIT 1
         SQL
 
-        # The signed id goes to `mandate_id`; the row id is server-generated and returned.
-        INTENT_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.intent_mandates
-            (mandate_id, user_id, agent_id, issuer, scope, cap_amount_cents,
-             currency, expires_at, created_at, raw_jws)
-          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, now(), $9)
-          RETURNING id
-        SQL
-
         # `line_items` arrives as JSON text; the cast stores a jsonb array rather than a string.
-        CART_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.cart_mandates
-            (mandate_id, intent_mandate_id, user_id, agent_id, issuer, line_items,
-             total_amount_cents, currency, expires_at, created_at, raw_jws)
+        CHECKOUT_INSERT_SQL = <<~SQL.squish
+          INSERT INTO %<schema>s.kiosk_checkout_mandates
+            (reference, checkout_hash, user_id, agent_id, issuer, line_items,
+             total_amount_cents, currency, expires_at, created_at, sd_jwt)
           VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8, $9, now(), $10)
           RETURNING id
         SQL
 
         PAYMENT_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.payment_mandates
-            (mandate_id, cart_mandate_id, user_id, agent_id, issuer,
-             payment_method, amount_cents, currency, expires_at, created_at, raw_jws)
+          INSERT INTO %<schema>s.kiosk_payment_mandates
+            (reference, checkout_mandate_id, user_id, agent_id, issuer,
+             payment_instrument, amount_cents, currency, expires_at, created_at, sd_jwt)
           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, now(), $10)
           RETURNING id
         SQL
 
-        # Nobody signs a settlement, so it has no `mandate_id` or `raw_jws`; `UNIQUE (cart_mandate_id)` keeps it single.
+        # Nobody signs a settlement; `UNIQUE (checkout_mandate_id)` keeps it single.
         SETTLEMENT_INSERT_SQL = <<~SQL.squish
-          INSERT INTO %<schema>s.settlements
-            (cart_mandate_id, user_id, agent_id, issuer, psp_reference,
-             settled_amount_cents, currency, settled_at)
-          VALUES ($1, $2, $3, $4, $5, $6, $7, now())
+          INSERT INTO %<schema>s.kiosk_settlements
+            (checkout_mandate_id, user_id, agent_id, issuer, psp_reference,
+             settled_amount_cents, currency, network_confirmation_id, settled_at)
+          VALUES ($1, $2, $3, $4, $5, $6, $7, $8, now())
           RETURNING id
         SQL
 
         DECLINE_SQL = <<~SQL.squish
-          UPDATE %<schema>s.cart_mandates SET declined_at = now() WHERE id = $1 AND declined_at IS NULL
+          UPDATE %<schema>s.kiosk_checkout_mandates SET declined_at = now() WHERE id = $1 AND declined_at IS NULL
         SQL
 
         private
 
         def chain_record(chain)
           connection.exec_query(ledger_sql(CHAIN_SQL), 'Kiosk chain lookup', [
-                                  identity.user_id, chain.cart.id, chain.cart.raw_jws, chain.intent.raw_jws,
-                                  chain.payment.raw_jws
+                                  identity.user_id, chain.checkout.reference, chain.checkout.sd_jwt, chain.payment.sd_jwt
                                 ]).to_a.first
         end
 
-        def decline_cart(cart_row)
-          connection.exec_query(ledger_sql(DECLINE_SQL), 'Kiosk cart decline', [cart_row])
-        end
-
-        def persist_intent_mandate(intent)
-          insert_returning_id('Kiosk intent_mandate insert', INTENT_INSERT_SQL, [
-                                intent.id, intent.user_id, intent.agent_id, intent.issuer, intent.scope,
-                                intent.cap_amount_cents.to_i, intent.currency, intent.expires_at, intent.raw_jws
-                              ])
+        def decline_checkout(checkout_row)
+          connection.exec_query(ledger_sql(DECLINE_SQL), 'Kiosk checkout decline', [checkout_row])
         end
 
-        # References the server intent id; the signed intent-cart binding is checked by MandateVerifier.
-        def persist_cart_mandate(cart, intent_row_id:)
-          insert_returning_id('Kiosk cart_mandate insert', CART_INSERT_SQL, [
-                                cart.id, intent_row_id, cart.user_id, cart.agent_id, cart.issuer,
-                                cart.line_items.to_json, cart.total_amount_cents.to_i, cart.currency,
-                                cart.expires_at, cart.raw_jws
+        def persist_checkout_mandate(checkout)
+          insert_returning_id('Kiosk checkout_mandate insert', CHECKOUT_INSERT_SQL, [
+                                checkout.reference, checkout.checkout_hash, checkout.user_id, checkout.agent_id,
+                                checkout.issuer, checkout.line_items.to_json, checkout.total_amount_cents,
+                                checkout.currency, checkout.expires_at, checkout.sd_jwt
                               ])
         end
 
-        def persist_payment_mandate(cart_row_id:, payment:)
-          # No presented payment method means the on-file card funded the charge.
-          pm_db = payment.payment_method.to_s.empty? ? 'on_file' : payment.payment_method
+        def persist_payment_mandate(checkout_row_id:, payment:)
           insert_returning_id('Kiosk payment_mandate insert', PAYMENT_INSERT_SQL, [
-                                payment.id, cart_row_id, payment.user_id, payment.agent_id, payment.issuer,
-                                pm_db, payment.amount_cents.to_i, payment.currency, payment.expires_at,
-                                payment.raw_jws
+                                payment.reference, checkout_row_id, payment.user_id, payment.agent_id, payment.issuer,
+                                payment.payment_instrument, payment.amount_cents, payment.currency, payment.expires_at,
+                                payment.sd_jwt
                               ])
         end
 
-        def persist_settlement(cart_row_id:, cart:, settled:)
+        def persist_settlement(checkout_row_id:, checkout:, settled:)
           insert_returning_id('Kiosk settlement insert', SETTLEMENT_INSERT_SQL, [
-                                cart_row_id, cart.user_id, cart.agent_id, cart.issuer,
-                                settled[:psp_reference], settled[:settled_amount_cents].to_i, cart.currency
+                                checkout_row_id, checkout.user_id, checkout.agent_id, checkout.issuer,
+                                settled[:psp_reference], settled[:settled_amount_cents].to_i, checkout.currency,
+                                settled[:network_confirmation_id]
                               ])
         end
 

data/lib/kiosk/server/failure_log.rb

@@ -2,18 +2,18 @@
 
 module Kiosk
   module Server
-    # Logs the exception whose message a refusal kept off the wire: Rails' logger, else `warn`.
+    # Logs the exception whose message a refusal kept out of the response: Rails' logger, else `warn`.
     # A raising logger is swallowed so one failure does not become two.
     module FailureLog
       # Enough frames to reach the operator's own code without flooding the log.
       BACKTRACE_FRAMES = 20
 
-      # One string to grep for refusals that kept their message off the wire.
+      # One string to grep for refusals that kept their message off the protocol.
       PREFIX = '[kiosk-server]'
 
       module_function
 
-      # `summary` is the caller's own words, the half that also reaches the wire.
+      # `summary` is the caller's own words, the half that also reaches the protocol.
       def report(summary, error)
         line = "#{PREFIX} #{summary}: #{error.message}\n  " \
                "#{Array(error.backtrace).first(BACKTRACE_FRAMES).join("\n  ")}"

data/lib/kiosk/server/handler_mixin.rb

@@ -5,8 +5,8 @@ require 'action_dispatch'
 
 module Kiosk
   module Server
-    # Implementation behind `include Kiosk::Handler`. The macros above a `def` make it a wire verb;
-    # a method with no pending declaration stays off the wire.
+    # Implementation behind `include Kiosk::Handler`. The macros above a `def` make it a verb;
+    # a method with no pending declaration stays off the protocol.
     module HandlerMixin
       KINDS = %i[action query].freeze
 
@@ -38,7 +38,7 @@ module Kiosk
         base.extend(ClassMethods)
         base.include(InstanceMethods)
 
-        # The wire authenticates by bearer token, never by cookie, so CSRF protection does not apply.
+        # The protocol authenticates by bearer token, never by cookie, so CSRF protection does not apply.
         base.skip_forgery_protection if base.respond_to?(:skip_forgery_protection)
 
         # Registered at include time, so an operator's own `rescue_from` declared later wins.
@@ -80,7 +80,7 @@ module Kiosk
 
         def bad_topic_name(owner, name)
           "#{owner} declared `topic #{name.inspect}`, which is not a legal Kiosk name. " \
-            "A topic name is a wire name: #{NAME_PATTERN.inspect}."
+            "A topic name matches #{NAME_PATTERN.inspect}."
         end
 
         def reserved_topic(owner, name)
@@ -300,12 +300,12 @@ module Kiosk
           kiosk_declare(method_name, pending)
         end
 
-        # Wire name → declaration for the verbs on this class, one per name.
+        # Published name → declaration for the verbs on this class, one per name.
         def kiosk_declarations
           @kiosk_declarations ||= {}
         end
 
-        # Wire name → declaration for the topics on this class.
+        # Published name → declaration for the topics on this class.
         def kiosk_topic_declarations
           @kiosk_topic_declarations ||= {}
         end
@@ -361,7 +361,7 @@ module Kiosk
 
         private
 
-        # The acting {Kiosk::Identity}; nil outside a wire request.
+        # The acting {Kiosk::Identity}; nil outside a protocol request.
         def kiosk_identity = CurrentRequest.identity
 
         # Differs from the method name only under `wire_name`.
@@ -376,8 +376,8 @@ module Kiosk
         end
 
         # A validation failure answers 400 with the errors' full messages. Any other raise Rails knows
-        # a status for maps to its lone wire code, its own message going to the operator's log and
-        # never onto the wire; anything else is re-raised.
+        # a status for maps to its lone error code, its own message going to the operator's log and
+        # never onto the protocol; anything else is re-raised.
         def kiosk_rescue_to_wire(exception)
           raise exception if exception.is_a?(Kiosk::Server::Errors::Base)
 

data/lib/kiosk/server/handler_registrations.rb

@@ -18,7 +18,7 @@ module Kiosk
           load_handlers_dir
           handlers.select! { |name| name.safe_constantize&.kiosk_register! }
           PaymentSetup.register! if Kiosk.configuration.payment_provider
-          Kyc.register! if Kiosk.configuration.kyc_provider
+          Kyc.register! if Kiosk.configuration.kyc_provider&.opens_verifications?
           refuse_cross_kind_collisions!
         end
 

data/lib/kiosk/server/handler_serving.rb

@@ -5,17 +5,17 @@ require 'json'
 module Kiosk
   module Server
     # How a controller that includes {Kiosk::Handler} answers a verb call.
-    # {Routing::VerbRoute} sends the wire request to the action that declares
+    # {Routing::VerbRoute} sends the protocol request to the action that declares
     # the verb. Around that action this module runs the gates of {VerbWire},
     # the session and the transaction, and writes the action's render as the
-    # wire answer.
+    # protocol answer.
     module HandlerServing
       include VerbWire
 
-      # The Rack env key where {Routing::VerbRoute} puts the wire name it routed.
+      # The Rack env key where {Routing::VerbRoute} puts the published name it routed.
       VERB_KEY = 'kiosk.verb'
 
-      # The one header of an action's render that reaches the wire: `Cache-Control`, on a 2xx (§3.7.4).
+      # The one header of an action's render that reaches the response: `Cache-Control`, on a 2xx (§3.7.4).
       PROPAGATED_HEADERS = %w[Cache-Control].freeze
 
       private
@@ -34,7 +34,7 @@ module Kiosk
         kiosk_render_refusal(Errors.malformed_json(hint: BODY_HINT))
       end
 
-      # The verb's {Result}: the wire's gates, then the action inside the session.
+      # The verb's {Result}: the protocol's gates, then the action inside the session.
       def kiosk_call(declaration, &)
         kind     = declaration[:kind]
         name     = @_kiosk_wire_name = declaration[:wire_name]
@@ -55,7 +55,7 @@ module Kiosk
         Answer.new(kind, @_kiosk_wire_name).value(status, kiosk_read_body(body), @_kiosk_page)
       end
 
-      # The action's `params` are the decoded arguments; the wire answers JSON whatever the caller's
+      # The action's `params` are the decoded arguments; the protocol answers JSON whatever the caller's
       # `Accept`, so an action's template is its `.json` one.
       def kiosk_wire_parameters!(args)
         request.set_header('action_dispatch.request.request_parameters', args.dup)
@@ -89,7 +89,7 @@ module Kiosk
         render_wire_error(error)
       end
 
-      # The action's render was read; the wire answer is written into a fresh response.
+      # The action's render was read; the protocol answer is written into a fresh response.
       def kiosk_fresh_response!
         set_response!(self.class.make_response!(request))
         @_response_body = nil
@@ -98,7 +98,7 @@ module Kiosk
       # A route drawn straight at a handler action, not through `kiosk do`, answers 404 `verb_not_found`.
       def kiosk_refuse_unrouted
         problem = Errors::VerbNotFound.new(
-          'Kiosk handlers are reachable through the Kiosk wire only',
+          'Kiosk handlers are reachable through the Kiosk HTTP API only',
           hint: "call the verb's own route — " \
                 "GET #{Kiosk.configuration.mount_path}/<query-name> or " \
                 "POST #{Kiosk.configuration.mount_path}/<action-name>"
@@ -107,7 +107,7 @@ module Kiosk
         render json: problem, status: :not_found, content_type: Errors::PROBLEM_CONTENT_TYPE
       end
 
-      # An action's render as the verb's answer: its payload, or the wire error it means.
+      # An action's render as the verb's answer: its payload, or the Kiosk error it means.
       class Answer
         def initialize(kind, wire_name)
           @kind      = kind
@@ -125,7 +125,7 @@ module Kiosk
 
         private
 
-        # 2xx → the rendered JSON; otherwise the wire error it means.
+        # 2xx → the rendered JSON; otherwise the Kiosk error it means.
         def decode(status, raw)
           return parse_json(raw) if status >= 200 && status < 300
 
@@ -172,7 +172,7 @@ module Kiosk
           raise Errors::ActionFailed.new(
             "#{@kind} #{@wire_name.inspect} rendered a non-JSON body",
             hint: 'a Kiosk handler answers with `render json:` — HTML, redirects and ' \
-                  '`send_file` have no place on the wire'
+                  '`send_file` have no place in a Kiosk response'
           )
         end
 

data/lib/kiosk/server/headers.rb

@@ -2,7 +2,7 @@
 
 module Kiosk
   module Server
-    # The Kiosk response headers and the cache policy of a wire response.
+    # The Kiosk response headers and the cache policy of a Kiosk response.
     module Headers
       def self.add_to(headers, server_version: Kiosk::Server::VERSION)
         headers[Kiosk::Protocol::HEADER_SERVER_VERSION] = server_version
@@ -18,7 +18,7 @@ module Kiosk
       # §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
+      # Adds the protocol `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)
@@ -56,7 +56,7 @@ module Kiosk
         '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: ' \
+        message = '[kiosk-server] refused a shared-cache policy on a Kiosk response: ' \
                   "Cache-Control: #{value.inspect}. #{SHARED_CACHE_RULE}"
         logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
         logger ? logger.warn(message) : warn(message)

data/lib/kiosk/server/identity_resolution.rb

@@ -2,8 +2,8 @@
 
 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
+    # The identity of a protocol or event-stream caller: the access token, read by
+    # the configured agent IdP or the bundled one. A cookie session
     # reaches only the human-side pages and the binding endpoints.
     module IdentityResolution
       module_function
@@ -12,8 +12,17 @@ module Kiosk
         Kiosk.configuration.agent_idp || AgentIdentityProviders::DefaultAgentIdp.new
       end
 
+      # The identity of the token, once the request's DPoP proof shows the key
+      # the token is bound to; nil with no valid token.
+      # @raise [Errors::AccessTokenRefused] a valid token without that proof
       def resolve(request)
-        agent_idp.verify(request)
+        identity = agent_idp.verify(request)
+        return if identity.nil?
+
+        Dpop.verify!(request.headers['DPoP'],
+                     token: Dpop.token(request.headers['Authorization']), jkt: identity.claims.dig(:cnf, :jkt),
+                     method: request.request_method, url: "#{Kiosk.current_issuer}#{request.path}")
+        identity
       end
     end
   end

data/lib/kiosk/server/jwk.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'digest'
+require 'json'
+require 'jwt'
+require 'openssl'
+
+module Kiosk
+  module Server
+    # The public keys Kiosk signs and verifies with, as OpenSSL keys and as
+    # JWKs: Ed25519 (RFC 8037, `kty` OKP, algorithm EdDSA) and P-256 (RFC 7518,
+    # `kty` EC, algorithm ES256).
+    module Jwk
+      # The JOSE algorithm of each key type.
+      ALGORITHMS = { 'OKP' => 'EdDSA', 'EC' => 'ES256' }.freeze
+
+      # The curve of each key type.
+      CURVES = { 'OKP' => 'Ed25519', 'EC' => 'P-256' }.freeze
+
+      module_function
+
+      def ed25519?(key) = key.is_a?(OpenSSL::PKey::PKey) && key.oid == 'ED25519'
+
+      def p256?(key) = key.is_a?(OpenSSL::PKey::EC) && key.group.curve_name == 'prime256v1'
+
+      # OpenSSL answers `private?` for an EC key only.
+      def private?(key)
+        return key.private? if key.is_a?(OpenSSL::PKey::EC)
+
+        key.raw_private_key
+        true
+      rescue OpenSSL::PKey::PKeyError
+        false
+      end
+
+      # `OKP`, `EC`, or nil for a key Kiosk does not use.
+      def kty(key)
+        if ed25519?(key) then 'OKP'
+        elsif p256?(key) then 'EC'
+        end
+      end
+
+      # The JOSE algorithm that `key` signs with, or nil.
+      def algorithm(key) = ALGORITHMS[kty(key)]
+
+      # The public members of `key`: the RFC 7638 required members.
+      def public_members(key)
+        case kty(key)
+        when 'OKP' then { crv: CURVES['OKP'], kty: 'OKP', x: b64(key.raw_public_key) }
+        when 'EC'
+          point = key.public_key.to_bn(:uncompressed).to_s(2)
+          { crv: CURVES['EC'], kty: 'EC', x: b64(point[1, 32]), y: b64(point[33, 32]) }
+        else raise ArgumentError, "Kiosk uses Ed25519 and P-256 keys, got #{key.class}"
+        end
+      end
+
+      # The public key of a JWK with the public members of its `kty`.
+      # @raise [ArgumentError] when the JWK is not an Ed25519 or a P-256 public key
+      def import(jwk)
+        jwk = jwk.transform_keys(&:to_s)
+        kty = jwk['kty']
+        raise ArgumentError, "the key type #{kty.inspect} is not OKP or EC" unless CURVES.key?(kty)
+        raise ArgumentError, "the curve of an #{kty} key is #{CURVES[kty]}" unless jwk['crv'] == CURVES[kty]
+
+        public_key(jwk)
+      rescue OpenSSL::PKey::PKeyError, ::JWT::JWKError
+        raise ArgumentError, "the key is not a valid #{kty} public key"
+      end
+
+      def public_key(jwk)
+        return OpenSSL::PKey.new_raw_public_key('ED25519', Base64.urlsafe_decode64(jwk['x'].to_s)) if jwk['kty'] == 'OKP'
+
+        ::JWT::JWK.import(jwk.slice('kty', 'crv', 'x', 'y')).verify_key
+      end
+
+      # RFC 7638: the SHA-256 of the required members, in alphabetical order.
+      def thumbprint(key) = b64(Digest::SHA256.digest(JSON.generate(public_members(key))))
+
+      def b64(bytes) = Base64.urlsafe_encode64(bytes, padding: false)
+    end
+  end
+end