kiosk-server 0.5.20

data/lib/kiosk/server/payment_claim.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require 'kiosk/uuid_check'
+
+module Kiosk
+  module Server
+    # §11.6 over a PSP adapter: claims the operator's payable row `unpaid →
+    # paying` before the capture, checks the cart against the operator's price,
+    # flips the row to `paid` once the capture returns, tells its owner on the
+    # `payment` topic, and runs `c.after_payment` once the settlement is recorded.
+    # A refund through it is recorded against the settlement.
+    class PaymentClaim
+      UNPAID = 'unpaid'
+      PAYING = 'paying'
+      PAID   = 'paid'
+      TOPIC  = 'payment'
+      EXAMPLE_ID = '5f0c2a8e-3b1d-4c6f-9a7e-2d8b4e1f6c03'
+
+      attr_reader :currency, :reference
+
+      # @param model [String] the payable model's name, e.g. "Order"; it includes Kiosk::Owned and Kiosk::Payable
+      # @param reference [String] the cart line-item key naming the row, e.g. "order_id"
+      # @param query [String] the per-user query that publishes the row's payment state
+      def initialize(psp, currency:, model:, reference:, query:)
+        @psp       = psp
+        @currency  = currency.to_s.downcase
+        @reference = reference
+        @query     = query
+        @row       = Row.new(model)
+        @options   = { currency:, model:, reference:, query: }
+        extend SetupReturn if psp.respond_to?(:setup_return_user_id)
+      end
+
+      # The same claim over another PSP adapter.
+      def over(psp) = self.class.new(psp, **@options)
+
+      def capture(cart_mandate, payment_method: nil) = charge_row(claim!(cart_mandate), cart_mandate, payment_method)
+
+      delegate :setup_required?, :setup_url, to: :@psp
+
+      # The settlements whose cart names this row.
+      def settlements(id) = Kiosk::Settlement.joins(:cart_mandate).merge(Kiosk::CartMandate.referencing(@reference => id))
+
+      def settled?(id) = settlements(id).exists?
+
+      # `paying → paid`, then the `payment` event, once: only the call that
+      # moved the row announces it. A failure here never surfaces: the charge
+      # has happened and the settlement row records it.
+      def mark_paid!(id)
+        announce(id, PAID) if @row.flip(id, from: PAYING, to: PAID).positive?
+      rescue StandardError => e
+        FailureLog.report("#{self.class} could not mark #{id} paid", e)
+        nil
+      end
+
+      # `paying → unpaid`, for a claim under which no money moved.
+      def release!(id) = @row.flip(id, from: PAYING, to: UNPAID)
+
+      private
+
+      def charge_row(id, cart_mandate, payment_method)
+        settled = charge(id, cart_mandate, payment_method)
+        mark_paid!(id)
+        settled
+      end
+
+      # Releases the claim when the PSP refuses before any money moved.
+      def charge(id, cart_mandate, payment_method)
+        @psp.capture(cart_mandate, payment_method: payment_method)
+      rescue Kiosk::PaymentProviders::SetupRequired
+        release!(id)
+        raise
+      rescue Kiosk::PaymentProviders::PaymentFailed => e
+        release!(id) if e.retryable?
+        raise
+      end
+
+      def claim!(cart)
+        id = referenced_id(cart)
+        refuse_unclaimable!(id, cart.user_id.to_s) unless @row.take(id, cart.user_id.to_s, from: UNPAID, to: PAYING).positive?
+        begin
+          check_price!(cart, id)
+        rescue StandardError
+          release!(id)
+          raise
+        end
+        id
+      end
+
+      # The one row the cart's line items name, in the operator's currency.
+      def referenced_id(cart)
+        deny "cart currency #{cart.currency.inspect} rejected — this operator prices in #{@currency.upcase}" unless cart.currency.to_s.downcase == @currency
+        Lines.reference(cart.line_items, @reference)
+      end
+
+      def check_price!(cart, id)
+        total = cart.total_amount_cents.to_i
+        lines = Array(cart.line_items).reject { |li| li[@reference] }
+        Lines.check_sum!(total, lines)
+
+        price = checker.call(id, lines)
+        deny price if price.is_a?(String)
+        return if total == price
+
+        deny "cart total #{total} does not equal this operator's price #{price} for #{noun} #{id} — " \
+             'sign the `cart` that the action which created it returned'
+      end
+
+      def checker
+        Kiosk.configuration.cart_price_checker or
+          raise Errors::ConfigurationError, "PaymentClaim needs c.cart_price_checker, the operator's price"
+      end
+
+      def refuse_unclaimable!(id, payer)
+        status = @row.status(id, payer)
+        deny "#{noun} not found or not yours" if status.nil?
+        refuse_paying!(id) if status == PAYING
+        deny "#{noun} #{id} is already paid (#{status}) — do not pay it again"
+      end
+
+      def refuse_paying!(id)
+        if settled?(id)
+          mark_paid!(id)
+          deny "#{noun} #{id} is already paid"
+        end
+        deny "#{noun} #{id} has a payment in progress under another chain. Send that chain again, " \
+             'byte for byte: it cannot charge twice. Do not sign a new chain. ' \
+             "GET <endpoint>/#{@query} shows the payment state."
+      end
+
+      def noun = @reference.delete_suffix('_id')
+
+      def deny(message)
+        raise Errors::Forbidden, message
+      end
+
+      # The cart's line items: the one row they name, and the priced lines' sum.
+      module Lines
+        module_function
+
+        def reference(line_items, key)
+          refs = Array(line_items).filter_map { |li| li[key] }.map(&:to_s).uniq
+          deny "cart line_items must reference exactly one #{key}" unless refs.size == 1
+          id = refs.first
+          return id if Kiosk::UuidCheck.valid?(id)
+
+          raise Errors::BadRequest.new("cart line_items #{key} #{id.inspect} is not a uuid",
+                                       hint: "use the `#{key}` this operator returned, verbatim")
+        end
+
+        # The priced lines, when any, sum to the cart total.
+        def check_sum!(total, lines)
+          priced = lines.select { |li| li['price_cents'] }
+          return if priced.empty?
+
+          sum = priced.sum do |li|
+            qty = li['qty'].to_i
+            price = li['price_cents'].to_i
+            deny 'each priced line needs a positive qty and price_cents' if qty <= 0 || price <= 0
+            qty * price
+          end
+          deny "cart total #{total} does not equal the sum of its line items #{sum}" unless total == sum
+        end
+
+        def deny(message)
+          raise Errors::Forbidden, message
+        end
+      end
+
+      # A repeat of a chain whose capture did not complete. The row stays with
+      # the newest unfinished chain, and the PSP keys the capture by the cart
+      # mandate id, so the repeat cannot charge twice.
+      module Resume
+        def resume(cart_mandate, payment_method: nil) = charge_row(reclaim!(cart_mandate), cart_mandate, payment_method)
+
+        private
+
+        # The row this repeated chain claimed, or the row it may claim now.
+        def reclaim!(cart)
+          id = referenced_id(cart)
+          payer = cart.user_id.to_s
+          status = @row.status(id, payer)
+          return claim!(cart) if status == UNPAID
+          return id if [PAYING, PAID].include?(status) && !settled?(id) && unfinished_chain(id, payer) == cart.id
+
+          refuse_unclaimable!(id, payer)
+        end
+
+        # The signed id of the newest cart for this row that is neither settled nor declined.
+        def unfinished_chain(id, payer)
+          Kiosk::CartMandate.referencing(@reference => id).where(user_id: payer, declined_at: nil)
+                            .where.missing(:settlements).order(created_at: :desc, id: :desc).pick(:mandate_id)
+        end
+      end
+      include Resume
+
+      # Money the operator gives back, recorded against its settlement.
+      module Refund
+        # Returns `amount_cents` of the charge `psp_reference` to the card and
+        # records the refund against its settlement, so recent spend leaves it
+        # out. `key` names this refund among the refunds of the charge: a repeat
+        # with the same key is the same refund, and is recorded once. The PSP's receipt.
+        def refund(psp_reference:, amount_cents:, key:)
+          receipt = @psp.refund(psp_reference:, amount_cents:, key:)
+          binds = receipt.values_at(:psp_reference, :refunded_amount_cents, :refunded_at, :refunded_psp_reference)
+          ::ActiveRecord::Base.lease_connection.exec_query(format(INSERT_SQL, schema: Kiosk.configuration.schema), 'Kiosk refund', binds)
+          receipt
+        end
+
+        INSERT_SQL = <<~SQL.squish
+          INSERT INTO "%<schema>s".refunds (settlement_id, psp_reference, refunded_amount_cents, refunded_at)
+          SELECT id, $1, $2, $3 FROM "%<schema>s".settlements WHERE psp_reference = $4
+          ON CONFLICT (psp_reference) DO NOTHING
+        SQL
+      end
+      include Refund
+
+      # The operator's work after a payment, which reads the settlement.
+      module AfterPayment
+        # The executor calls this once, after it records the settlement of
+        # `cart_mandate`, so `c.after_payment` reads the row's `settlement`. A
+        # failure here never surfaces on the wire: the log carries it.
+        def settled(cart_mandate)
+          id = Lines.reference(cart_mandate.line_items, @reference)
+          Kiosk.configuration.after_payment&.call(id)
+        rescue StandardError => e
+          FailureLog.report("#{self.class} after_payment failed for #{id}", e)
+          nil
+        end
+      end
+      include AfterPayment
+
+      # The `payment` topic, which the engine serves beside `payment_setup`, and
+      # its events: where the money for one row stands.
+      module Topic
+        # Tells the row's owner where its money stands: `paid` or `refunded`.
+        def announce(id, payment_state)
+          Events.emit(topic: TOPIC, subject: id, identity_scope: [@row.owner(id)],
+                      data: { @reference => id, 'payment_state' => payment_state })
+        end
+
+        def topic
+          @topic ||= { name: TOPIC, reach: :principal,
+                       description: "The money for one #{noun} of yours moved. `paid`: the charge went through. " \
+                                    '`refunded`: the charge went back to the card.',
+                       payload_schema: { type: 'object', additionalProperties: false,
+                                         properties: { @reference => { type: 'string', format: 'uuid' },
+                                                       'payment_state' => { enum: [PAID, Kiosk::Payable::REFUNDED] } },
+                                         required: [@reference, 'payment_state'] },
+                       examples: [PAID, Kiosk::Payable::REFUNDED].map { { @reference => EXAMPLE_ID, 'payment_state' => it } },
+                       subject_reachable: ->(id, identity) { !@row.status(id, identity.user_id.to_s).nil? } }.freeze
+        end
+      end
+      include Topic
+
+      # The PSP names whose human came back from the setup page; the engine
+      # serves the `payment_setup` topic only for a provider that has this method.
+      module SetupReturn
+        delegate :setup_return_user_id, to: :@psp
+      end
+
+      # The operator's payable rows: the status moves under a compare-and-set.
+      class Row
+        def initialize(model)
+          @model = model
+        end
+
+        # Moves this payer's row `from → to`; the count of rows moved, 0 or 1.
+        def take(id, payer, from:, to:) = move(model.owned_by(payer).where(id:), from:, to:)
+
+        def status(id, payer) = model.owned_by(payer).where(id:).pick(:payment_status)
+
+        def owner(id) = model.where(id:).pick(:user_id)
+
+        def flip(id, from:, to:) = move(model.where(id:), from:, to:)
+
+        private
+
+        def move(rows, from:, to:)
+          # One conditional UPDATE is the atomic compare-and-set: the row count says which caller won.
+          rows.where(payment_status: from).update_all({ payment_status: to }.merge(timestamps)) # rubocop:disable Rails/SkipsModelValidations -- a per-row save cannot move a row atomically
+        end
+
+        def timestamps
+          now = model.current_time_from_proper_timezone
+          model.timestamp_attributes_for_update_in_model.index_with { now }
+        end
+
+        def model = @model.constantize
+      end
+    end
+  end
+end

data/lib/kiosk/server/payment_setup.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # `payment_setup`: can this principal pay now, or which page must their
+    # human finish first. Served on every origin with a `payment_provider`.
+    module PaymentSetup
+      NAME        = 'payment_setup'
+      RETURN_PATH = 'payment_setup/return'
+
+      DESCRIPTION =
+        'Check whether you can pay now. Returns {status: "ready"} when `pay` will be accepted. ' \
+        'Returns {status: "setup_required", setup_url: "…"} when your human must first open ' \
+        'setup_url and finish there (for example, save a card); call payment_setup again ' \
+        'before paying. Call it before `pay`. ' \
+        'POLLING, where this origin publishes no payment_setup topic: while your human is at ' \
+        'the page, re-check every ~5 seconds for the first minute, then every ~15 seconds, and ' \
+        'GIVE UP after about 5 minutes — tell your human the setup is still not finished rather ' \
+        'than polling indefinitely; they can finish later and you re-check then. ' \
+        'Relay ONE link: if a later check returns a different url, leave your human on the page ' \
+        'they already have open unless they say it stopped working.'
+
+      INPUT_SCHEMA = { type: 'object', additionalProperties: false, properties: {}, required: [] }.freeze
+
+      OUTPUT_SCHEMA = {
+        oneOf: [
+          { type: 'object', additionalProperties: false,
+            description: 'Nothing to set up — proceed to `pay`.',
+            properties: { status: { const: 'ready' } },
+            required: ['status'] },
+          { type: 'object', additionalProperties: false,
+            description: 'Your human must finish the page at setup_url first.',
+            properties: {
+              status: { const: 'setup_required' },
+              setup_url: { type: 'string', description: 'The page to hand to your human.' }
+            },
+            required: %w[status setup_url] }
+        ]
+      }.freeze
+
+      TOPIC = {
+        name: NAME,
+        reach: :principal,
+        description: 'Your human finished the payment setup. `pay` will now be accepted — ' \
+                     'no further payment_setup call is needed.',
+        payload_schema: { type: 'object', additionalProperties: false,
+                          properties: { status: { enum: %w[ready] } },
+                          required: %w[status] },
+        subject_reachable: ->(subject, identity) { subject.to_s == identity.user_id.to_s }
+      }.freeze
+
+      class << self
+        def provider = Kiosk.configuration.payment_provider
+
+        def served!
+          return if provider
+
+          raise Errors::ModuleNotServed.new(
+            'this operator does not serve the payment module',
+            hint: "`pay` is absent from this origin's capabilities; hand the transaction to your human"
+          )
+        end
+
+        # Publishes the action; the topic when the provider can say whose human
+        # came back from the setup page; and a PaymentClaim's `payment` topic.
+        def register!
+          Actions.declare(NAME, method(:call), description: DESCRIPTION,
+                                               input_schema: INPUT_SCHEMA, output_schema: OUTPUT_SCHEMA)
+          Events.register(**TOPIC) if provider.respond_to?(:setup_return_user_id)
+          Events.register(**provider.topic) if provider.respond_to?(:topic)
+        end
+
+        def call(_args)
+          user_id = CurrentRequest.identity.user_id
+          return { 'status' => 'ready' } unless provider.setup_required?(user_id: user_id)
+
+          { 'status' => 'setup_required', 'setup_url' => provider.setup_url(user_id: user_id, return_url: return_url) }
+        end
+
+        def return_url
+          "#{Kiosk.current_issuer.to_s.chomp('/')}#{Kiosk.configuration.mount_path}/#{RETURN_PATH}"
+        end
+
+        # Unauthenticated, so only a hint: the provider names the principal and
+        # readiness is asked again. Never raises.
+        def returned(params)
+          return false unless Events.fetch(NAME)
+
+          user_id = provider.setup_return_user_id(params).to_s
+          return false if user_id.empty? || provider.setup_required?(user_id: user_id)
+
+          Events.emit(topic: NAME, subject: user_id, identity_scope: [user_id],
+                      data: { 'status' => 'ready' })
+          true
+        rescue StandardError => e
+          FailureLog.report("#{RETURN_PATH} could not push #{NAME}", e)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/pop_verifier.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'openssl'
+require 'rails'
+
+module Kiosk
+  module Server
+    # Verifies an agent's proof-of-possession JWS: RS256 by the presented key,
+    # `aud` equal to this origin (the relay defence), and the challenge `nonce`.
+    # The caller burns the nonce only after a clean verify.
+    module PopVerifier
+      # Names no origin: an echoed one 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 echoed back in a response'
+
+      PROOF_REQUIRED_CLAIMS = %w[aud nonce jti].freeze
+
+      MAX_KEY_BITS = 4096
+
+      PROOF_CLAIMS_HINT =
+        "a proof's payload carries #{PROOF_REQUIRED_CLAIMS.join(', ')} — `aud` is the origin " \
+        'you connected to, `nonce` the value GET /auth/challenge just issued for this key, ' \
+        '`jti` a unique id for this proof'.freeze
+
+      PROOF_SIGNATURE_HINT =
+        'a proof is a compact RS256 JWS — header.payload.signature — signed with the ' \
+        'private key matching the public_key you sent'
+
+      module_function
+
+      def verify!(public_key_pem:, signed:)
+        pem = public_key_pem.to_s.strip
+        payload = decode(signed, load_public_key(pem))
+        check_audience!(payload[:aud])
+        raise Errors::Unauthenticated, 'proof key thumbprint mismatch' if payload.key?(:pub) && payload[:pub] != SigningKey.from_pem(pem).kid
+
+        payload
+      end
+
+      def decode(signed, key)
+        payload, = ::JWT.decode(signed.to_s, key, true, algorithms: ['RS256'], required_claims: PROOF_REQUIRED_CLAIMS)
+        payload.transform_keys(&:to_sym)
+      rescue ::JWT::MissingRequiredClaim
+        raise Errors::Unauthenticated.new('proof is missing a required claim', hint: PROOF_CLAIMS_HINT)
+      rescue ::JWT::DecodeError
+        raise Errors::Unauthenticated.new('proof signature invalid', hint: PROOF_SIGNATURE_HINT)
+      end
+
+      def check_audience!(signed_aud)
+        issuer = Kiosk.current_issuer
+        return if signed_aud == issuer
+
+        log_audience_mismatch(signed_aud: signed_aud, issuer: issuer)
+        raise Errors::Unauthenticated.new('proof audience mismatch', hint: AUDIENCE_HINT)
+      end
+
+      # Operator log only, since the response must not name an origin: the
+      # caller signed a wrong value, or the origin it reached is not served.
+      def log_audience_mismatch(signed_aud:, issuer:)
+        message = "[kiosk] PoP audience mismatch: caller signed aud=#{signed_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
+
+      # Also the key bounds of account binding.
+      def load_public_key(pem)
+        OpenSSL::PKey::RSA.new(pem).tap { require_key_size!(it.n.num_bits) }
+      rescue OpenSSL::PKey::PKeyError
+        raise Errors::BadRequest.new(
+          'invalid public key',
+          hint: "send a PEM-encoded RSA public key of #{SigningKey::MIN_KEY_BITS} to #{MAX_KEY_BITS} bits " \
+                '(-----BEGIN PUBLIC KEY----- …)'
+        )
+      end
+
+      def require_key_size!(bits)
+        raise Errors::BadRequest, "public key too small (#{bits} bits; minimum #{SigningKey::MIN_KEY_BITS})" if bits < SigningKey::MIN_KEY_BITS
+        raise Errors::BadRequest, "public key too large (#{bits} bits; maximum #{MAX_KEY_BITS})" if bits > MAX_KEY_BITS
+      end
+    end
+  end
+end

data/lib/kiosk/server/pow_gate.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Kiosk
+  module Server
+    # The proof-of-work toll, in front of every verb that reaches the executor.
+    # It is paid once per access token: after one paid toll, every call made
+    # with that token proceeds until the token expires. With no
+    # `reputation_policy` it returns `:proceed` and touches nothing;
+    # `kiosk-reputation` is required only when a policy is set.
+    module PowGate
+      module_function
+
+      # §10, §15.2: SHA256("<METHOD> <verb>\n<canonical args>"), so a proof is
+      # spendable on this request only. The proof rides in a header, not the body.
+      def request_fingerprint(method:, verb:, body:)
+        Digest::SHA256.hexdigest(
+          "#{method.to_s.upcase} #{verb}\n#{canonical_json(body || {})}"
+        )
+      end
+
+      # `command` is the policy verb ({Executor::VERBS}); `verb` is the wire name
+      # the fingerprint binds.
+      def gate(identity:, command:, body:, pow:, method: 'POST', verb: nil) # rubocop:disable Metrics/ParameterLists -- the wire controller and the specs pass these six by name
+        config = Kiosk.configuration
+        policy = config.reputation_policy
+        return :proceed if policy.nil? || session_paid?(config, identity)
+
+        secret = pow_secret!(config)
+        spec   = toll_for(policy, identity, command.to_sym)
+        return :proceed if spec.nil?
+
+        fp = request_fingerprint(method: method, verb: verb || command, body: body)
+        PowToll.new(spec: spec, fingerprint: fp, secret: secret, config: config)
+               .collect!(pow).tap { paid(config, identity) }
+      end
+
+      def session_paid?(config, identity)
+        session = session_id(identity)
+        !session.nil? && config.pow_spent_store.spent?(session)
+      end
+
+      # Records the token's session as paid.
+      def paid(config, identity)
+        session = session_id(identity)
+        config.pow_spent_store.mark_spent(session, identity.claims[:exp]) if session
+      end
+
+      # The access token a toll pays for, by its `jti`, or nil for a caller without one.
+      def session_id(identity)
+        claims = identity&.claims || {}
+        "session:#{claims[:jti]}" if claims[:jti] && claims[:exp]
+      end
+
+      # The policy's toll for this caller and verb, or nil for none.
+      def toll_for(policy, identity, verb)
+        policy.challenge_for(identity: identity, verb: verb, factors: ReputationFactors.for(identity:, policy:))
+      end
+
+      def pow_secret!(config)
+        unless defined?(::Kiosk::Reputation)
+          raise Errors::ConfigurationError,
+                'Kiosk::Server: reputation_policy is set but kiosk-reputation is not loaded. ' \
+                "Add `require 'kiosk/reputation'` (and `gem 'kiosk-reputation'`) to your app."
+        end
+
+        secret = config.pow_secret
+        return secret unless secret.nil? || secret.to_s.strip.empty?
+
+        raise Errors::ConfigurationError,
+              'Kiosk::Server: reputation_policy is set but pow_secret is nil or empty. ' \
+              "Set: Kiosk.configure { |c| c.pow_secret = ENV.fetch('KIOSK_POW_SECRET') }"
+      end
+
+      # One proof, a JSON array, repeated header lines (Rack joins them with
+      # "\n") or comma-joined ones; nil when absent.
+      def proofs_from_header(raw)
+        return nil if raw.nil?
+
+        proofs = raw.split("\n").map(&:strip).reject(&:empty?).flat_map { |value| proofs_in(value) }
+        proofs.empty? ? nil : proofs
+      rescue JSON::ParserError
+        raise Errors::BadRequest.new('malformed Kiosk-PoW header', hint: POW_HEADER_HINT)
+      end
+
+      def proofs_in(value)
+        Array(JSON.parse(value.start_with?('[') ? value : "[#{value}]", symbolize_names: true))
+      end
+
+      POW_HEADER_HINT =
+        'the Kiosk-PoW header carries the proof(s) as raw minified JSON: a single ' \
+        'proof {"challenge": <the challenge object from the 402, echoed verbatim>, ' \
+        '"nonce": {"indices": […], "header_nonce"?}}, OR a JSON array of such ' \
+        'proofs [{…},{…}]. Repeated Kiosk-PoW header lines (one proof each) also ' \
+        'work. Solve every challenge issued in the pow_required 402 and echo it ' \
+        'back verbatim.'
+
+      # Unversioned: the server cannot know which skill cut its caller read.
+      POW_SOLVER_URL = 'https://kiosk.tech/pow/solve.py'
+
+      POW_INVALID_HINT =
+        "solve with the reference solver at #{POW_SOLVER_URL} — " \
+        'a hand-written Equihash solver will not match this verifier'.freeze
+
+      def canonical_json(obj)
+        case obj
+        when Hash
+          pairs = obj.sort_by { |k, _| k.to_s }
+                     .map { |k, v| "#{JSON.generate(k.to_s)}:#{canonical_json(v)}" }
+          "{#{pairs.join(',')}}"
+        when Array
+          "[#{obj.map { |v| canonical_json(v) }.join(',')}]"
+        else
+          JSON.generate(obj)
+        end
+      end
+    end
+  end
+end