x402-rack 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98f4be71b3158fb9a60f48c7fd22fab18bf11f7e299bbd482a34ed1ff0d43f5b
-  data.tar.gz: 52abd02a198410c35b10d07247a290c1e2d1ec6c971758b160be7c5956d01fa7
+  metadata.gz: f3b7c632a276b60aa31022985a02b8b9e1722cef5e11fbe0ee626f8d5c2fac98
+  data.tar.gz: 791f68f8b62750f1e3741404e3ed551b6a7f97f8160f42eeb76be1db551dc4c8
 SHA512:
-  metadata.gz: 22f092945c96c25969074be4f70d9af80ced8e2a60fff3ff02d4b851e77758a754cfca4b337e341abcb7fcb6c0eb8623ee0aa9b46526991ea406579ed9c3e483
-  data.tar.gz: ce2373b9e168bf1dea3d5f39a97b870007f58d1b74fe6cec8c7dd172b10c4daa4dda1bbe9156fe94ca43cd1dc3399db67f92db1b4e92e860d0ac982f682cff1f
+  metadata.gz: 8d3df96ff711728a23d5e8bc6ef2b62085e19904ec7810e0dfd26af47114b258e23d0064aa952ea19a0a0479c04398ac682b4f0b596a7597ef31721e2b1c02c6
+  data.tar.gz: f270706245222660c689860335f8d204d484819ddb8d9dc176fe10d51633d339d137c8a53de0d71f805cbd3eb8605dd6c3f1c1836f2251b7b2ad67bb26403b74

data/.yardopts

@@ -0,0 +1,6 @@
+--plugin markdown
+--markup markdown
+--output-dir doc
+lib/**/*.rb
+-
+CHANGELOG.md

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-04-05
+
+### Added
+
+- **Configurable structured logging** — pluggable `logger` on configuration with structured request lifecycle messages (route match, identity key, proof dispatch, settlement outcome). (#102)
+- **BRC-105 settlement logging** — structured log output for derivation, key ID, locking script verification, and settlement result in `BRC105Gateway`. (#96)
+- **BRC-105 §6.2 response body** — settlement success and error responses now include spec-conformant JSON body with receipt details. Spec-anchored tests. (#91)
+- **BRC-105 response headers** — `x-bsv-payment-version` and `x-bsv-payment-satoshis-paid` headers on successful settlement. (#91)
+- **API documentation** — YARD-style docs for public interfaces. (#89)
+
+### Changed
+
+- **Client identity key required for BRC-105** — `x-bsv-auth-identity-key` header is now mandatory for BRC-105 settlement (§7.1). Requests without it receive a 401 error. (#99)
+
+### Fixed
+
+- **ARC broadcast error details** — error messages from ARC are now logged and surfaced in the 502 response rather than swallowed silently.
+- **Base64 `derivationSuffix` accepted** — client-generated suffixes may be base64-encoded (not just hex). Validation updated to accept both formats. (#93)
+
+### Build
+
+- **Dependency updates** — bsv-sdk 0.6.0 → 0.6.1, rack 3.2.6.
+
 ## [0.5.1] - 2026-04-04
 
 ### Fixed

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-x402-rack is a Ruby gem providing Rack middleware for the x402 protocol (BSV settlement-gated HTTP). Currently in early development (v0.1.0). Requires Ruby >= 3.1.
+x402-rack is a Ruby gem providing Rack middleware for the x402 protocol (BSV settlement-gated HTTP). Requires Ruby >= 3.1.
 
 ## Commands
 
@@ -31,20 +31,9 @@ bundle exec rubocop -A
 bundle exec rake
 ```
 
-## Architecture
+## Specifications
 
-Standard Ruby gem layout generated by `bundle gem`:
-
-- `lib/x402.rb` — main entry point, defines `X402` module
-- `lib/x402/version.rb` — version constant
-- `lib/x402/middleware.rb` — pure dispatcher (no blockchain knowledge)
-- `lib/x402/bsv/gateway.rb` — base class for template-based gateways
-- `lib/x402/bsv/pay_gateway.rb` — Coinbase v2 headers, server broadcasts
-- `lib/x402/bsv/proof_gateway.rb` — merkleworks headers, client broadcasts
-- `lib/x402/bsv/brc105_gateway.rb` — BSV Association BRC-105, BRC-29 derivation (no inheritance from Gateway)
-- `lib/x402/bsv/prefix_store.rb` — pluggable replay protection for BRC-105 derivation prefixes
-- `sig/x402.rbs` — RBS type signatures
-- `x402-rack.gemspec` — gem specification (dependencies defined here, not in Gemfile)
+This project implements published protocol specifications (BRC-105, BRC-29, etc.). When writing or modifying code that implements a spec, consult the spec directly (via `bsv-protocol-docs` MCP) and verify conformance — including optional features unless there is a documented reason to omit them. Tests should be anchored to spec requirements, not just implementation behaviour.
 
 ## Code Style
 

data/Rakefile

@@ -16,3 +16,49 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+def generate_reference_index(output_dir)
+  require "csv"
+  csv_path = File.join(output_dir, "index.csv")
+  return unless File.exist?(csv_path)
+
+  modules = []
+  classes = []
+  CSV.foreach(csv_path, headers: true) do |row|
+    next unless %w[Module Class].include?(row["type"])
+
+    entry = { name: row["name"], path: row["path"] }
+    row["type"] == "Module" ? modules << entry : classes << entry
+  end
+
+  File.open(File.join(output_dir, "index.md"), "w") do |f|
+    f.puts "# API Reference"
+    f.puts
+    f.puts "Auto-generated from source using [YARD](https://yardoc.org/)."
+    f.puts
+    f.puts "## Modules"
+    f.puts
+    modules.sort_by { |e| e[:name] }.each { |e| f.puts "- [#{e[:name]}](#{e[:path]})" }
+    f.puts
+    f.puts "## Classes"
+    f.puts
+    classes.sort_by { |e| e[:name] }.each { |e| f.puts "- [#{e[:name]}](#{e[:path]})" }
+  end
+end
+
+namespace :docs do
+  desc "Generate YARD markdown into docs/reference/"
+  task :generate do
+    require "fileutils"
+    output_dir = "docs/reference"
+    FileUtils.rm_rf(output_dir)
+    FileUtils.mkdir_p(output_dir)
+    sh "bundle exec yardoc --plugin markdown --format markdown --output-dir docs/reference lib/**/*.rb"
+    generate_reference_index(output_dir)
+  end
+
+  desc "Generate docs and serve locally with MkDocs"
+  task serve: :generate do
+    sh "mkdocs serve"
+  end
+end

data/docs/index.md

@@ -0,0 +1,21 @@
+# x402-rack
+
+Rack middleware for payment-gated HTTP using BSV and the [x402 protocol](https://docs.x402.org/).
+
+The middleware is a pure dispatcher — it matches routes, issues payment challenges, and routes proofs to pluggable gateway backends for settlement. It has no blockchain knowledge and holds no keys.
+
+## Three BSV settlement schemes
+
+- **BSV-pay** (Coinbase v2 headers) — server broadcasts via ARC. No nonces, minimal infrastructure.
+- **BSV-proof** (merkleworks x402) — client broadcasts, server checks mempool. Nonce-bound, request-binding.
+- **BRC-105** (BSV Association `x-bsv-*` headers) — BRC-29 key derivation for unique payment addresses. Works standalone or composes with BRC-103 mutual authentication.
+
+## Getting started
+
+Add to your Gemfile:
+
+```ruby
+gem "x402-rack", git: "https://github.com/sgbett/x402-rack.git"
+```
+
+See the [Architecture](architecture.md) guide for how the pieces fit together, or jump to the [API Reference](reference/index.md) for class and method documentation.

data/docs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs>=1.6.0
+mkdocs-material>=9.6.0
+mkdocs-minify-plugin>=0.8.0

data/docs/schemes/brc-105.md

@@ -1,5 +1,9 @@
 # BRC-105 Scheme (BSV Association)
 
+The official BSV Association [BRC-105](https://github.com/bitcoin-sv/BRCs/blob/master/payments/0105.md) payment protocol. Currently standalone (no-auth) mode — BRC-103 mutual authentication coming soon.
+
+## Description
+
 BRC-29 derived payment addresses with AtomicBEEF transactions. BSV Association `x-bsv-*` headers. Optional BRC-103 mutual authentication.
 
 Unlike BSV-pay and BSV-proof, this scheme does not use partial transaction templates. The client builds the entire transaction using a derived payment address.

data/docs/schemes/bsv-pay.md

@@ -1,5 +1,9 @@
 # BSV-pay Scheme
 
+The default gateway. Direct peer-to-peer payment — client pays server, server broadcasts to the network.
+
+## Description
+
 Server broadcasts via ARC. Uses Coinbase v2 header spec. Minimal infrastructure — ARC only, no treasury, no nonces.
 
 ## Headers
@@ -70,4 +74,4 @@ See [operations/performance.md](../operations/performance.md) for scaling consid
 
 ## Process Flow
 
-See [process-flow/pay_gateway.md](../process-flow/pay_gateway.md) for sequence diagrams.
+See [process-flow/pay-gateway.md](../process-flow/pay-gateway.md) for sequence diagrams.

data/docs/schemes/bsv-proof.md

@@ -1,5 +1,16 @@
 # BSV-proof Scheme (merkleworks x402)
 
+The [merkleworks x402](https://x402.merkleworks.io) implementation. Client broadcasts and proves payment via mempool.
+
+!!! danger "Experimental — not production-ready"
+    The ProofGateway implementation is incomplete and under active development.
+    The nonce provider interface, Profile B provenance verification, and mempool
+    checking behaviour may change without notice. **Do not use in production.**
+    For production BSV payments, use [BSV-pay](bsv-pay.md) (PayGateway) or
+    [BRC-105](brc-105.md) (BRC105Gateway).
+
+## Description
+
 Client broadcasts, server checks mempool. Proof-of-payment model. Nonce-bound with request binding.
 
 ## Headers

data/lib/x402/bsv/brc105_gateway.rb

@@ -22,8 +22,9 @@ module X402
       PROTOCOL_ID = [2, "3241645161d8"].freeze
       PROOF_HEADER = "x-bsv-payment"
       NETWORK = "bsv:mainnet"
-      COMPRESSED_PUBKEY_HEX = /\A0[23][0-9a-fA-F]{64}\z/
+      COMPRESSED_PUBKEY_HEX = /\A0[23][0-9a-f]{64}\z/
       MAX_DERIVATION_BYTES = 64
+      PRINTABLE_ASCII = /\A[\x20-\x7E]+\z/
 
       # @param key_deriver [BSV::Wallet::KeyDeriver] provides identity key + BRC-42 derivation
       # @param prefix_store [#store!, #valid?, #consume!] replay protection for derivation prefixes
@@ -48,11 +49,15 @@ module X402
         end
 
         headers = {
+          "x-bsv-payment-version" => "1.0",
           "x-bsv-payment-satoshis-required" => route.resolve_amount_sats.to_s,
           "x-bsv-payment-derivation-prefix" => prefix
         }
 
-        # Include identity key only in standalone mode (no BRC-103 present)
+        # The 402 challenge is issued before the client authenticates (no
+        # x-bsv-auth-identity-key yet). Include the server's identity key so
+        # the client knows who to derive the payment address for. When BRC-103
+        # mutual auth is already established, the client already has this key.
         headers["x-bsv-payment-identity-key"] = @key_deriver.identity_key unless validated_brc103_key(rack_request)
 
         headers
@@ -73,17 +78,23 @@ module X402
       # @param route [X402::Configuration::Route]
       # @return [SettlementResult]
       def settle!(_header_name, proof_payload, rack_request, route)
+        # §7.1: fail fast if unauthenticated — before parsing untrusted payload
+        counterparty = resolve_counterparty(rack_request)
         required_sats = route.resolve_amount_sats
         payment = parse_payment(proof_payload)
         prefix = payment["derivationPrefix"]
         suffix = payment["derivationSuffix"]
         validate_prefix_and_suffix!(prefix, suffix)
         subject_tx = parse_beef_transaction(payment["transaction"])
+        log_derivation_inputs(prefix, suffix, counterparty)
         expected_script = derive_payment_script(prefix, suffix, rack_request)
-        verify_payment_output!(subject_tx, required_sats, expected_script)
+        log_expected_script(expected_script)
+        log_tx_outputs(subject_tx, required_sats, expected_script)
+        paid_sats = verify_payment_output!(subject_tx, required_sats, expected_script)
         consume_prefix!(prefix)
         broadcast!(subject_tx)
-        build_settlement_result(subject_tx)
+        log_settlement_success(subject_tx, paid_sats, required_sats)
+        build_settlement_result(subject_tx, paid_sats)
       end
 
       private
@@ -95,11 +106,12 @@ module X402
       end
 
       def validate_prefix_and_suffix!(prefix, suffix)
-        validate_derivation_component!("derivationPrefix", prefix)
-        validate_derivation_component!("derivationSuffix", suffix)
+        validate_hex!("derivationPrefix", prefix)
+        validate_suffix!("derivationSuffix", suffix)
       end
 
-      def validate_derivation_component!(name, value)
+      # Prefix is server-generated hex (SecureRandom.hex).
+      def validate_hex!(name, value)
         raise VerificationError.new("missing #{name}", status: 400) if value.nil?
         unless value.is_a?(String) && !value.empty? &&
                value.bytesize <= MAX_DERIVATION_BYTES && value.match?(/\A[0-9a-f]+\z/)
@@ -107,6 +119,17 @@ module X402
         end
       end
 
+      # Suffix is client-generated — the BRC-105 spec does not constrain the
+      # format. Reference implementations (BRC-121, bsv-x402) use base64.
+      # We accept any printable ASCII string within the size limit.
+      def validate_suffix!(name, value)
+        raise VerificationError.new("missing #{name}", status: 400) if value.nil?
+        unless value.is_a?(String) && !value.empty? &&
+               value.bytesize <= MAX_DERIVATION_BYTES && value.match?(PRINTABLE_ASCII)
+          raise VerificationError.new("invalid #{name} format", status: 400)
+        end
+      end
+
       def consume_prefix!(prefix)
         return if @prefix_store.consume!(prefix)
 
@@ -138,42 +161,95 @@ module X402
         ::BSV::Script::Script.from_hex("76a914#{h160}88ac")
       end
 
+      # BRC-105 §7.1: "If not authenticated, respond 401 Unauthorized."
+      # The client's identity key is required for BRC-42 key derivation.
       def resolve_counterparty(rack_request)
-        validated_brc103_key(rack_request) || "anyone"
+        key = rack_request.env["brc103.identity_key"]
+        return key if key.is_a?(String) && key.match?(COMPRESSED_PUBKEY_HEX)
+
+        if key.nil? || (key.is_a?(String) && key.empty?)
+          raise VerificationError.new("missing client identity key (x-bsv-auth-identity-key)", status: 401)
+        end
+
+        raise VerificationError.new("invalid client identity key (x-bsv-auth-identity-key)", status: 401)
       end
 
       # Returns the validated BRC-103 identity key from the Rack env, or nil
       # if absent or not a valid compressed public key hex.
+      # Used by challenge_headers to check for BRC-103 presence.
       def validated_brc103_key(rack_request)
         key = rack_request.env["brc103.identity_key"]
         key if key.is_a?(String) && key.match?(COMPRESSED_PUBKEY_HEX)
       end
 
       def verify_payment_output!(transaction, required_sats, expected_script)
-        found = transaction.outputs.any? do |output|
+        matching = transaction.outputs.find do |output|
           output.locking_script == expected_script && output.satoshis >= required_sats
         end
-        return if found
 
-        raise VerificationError.new(
-          "no output pays >= #{required_sats} sats to derived address", status: 402
-        )
+        unless matching
+          raise VerificationError.new(
+            "no output pays >= #{required_sats} sats to derived address", status: 402
+          )
+        end
+
+        matching.satoshis
       end
 
       def broadcast!(transaction)
         @arc_client.broadcast(transaction)
-      rescue StandardError
-        raise VerificationError.new("ARC broadcast failed", status: 502)
+      rescue StandardError => e
+        logger.error "[brc105] ARC broadcast error: #{e.class}: #{e.message}"
+        raise VerificationError.new("ARC broadcast failed: #{e.message}", status: 502)
+      end
+
+      # NOTE: x-bsv-payment-satoshis-paid reflects the amount claimed in the
+      # BEEF transaction, verified against the derived payment script but set
+      # before ARC broadcast confirmation. It is not an on-chain-confirmed
+      # value. Downstream consumers requiring confirmed amounts should use
+      # the txid to query chain state independently.
+      # --- Settlement logging (tagged [brc105]) ---
+
+      def logger
+        X402.configuration.logger
+      end
+
+      def log_derivation_inputs(prefix, suffix, counterparty)
+        logger.info "[brc105] Derivation: prefix=#{prefix} suffix=#{suffix} counterparty=#{counterparty}"
+        logger.debug "[brc105] Key ID: #{prefix} #{suffix}"
+      end
+
+      def log_expected_script(script)
+        logger.info "[brc105] Expected locking script: #{script.to_hex}"
+      end
+
+      def log_tx_outputs(transaction, required_sats, expected_script)
+        logger.info "[brc105] Verifying #{transaction.outputs.length} output(s) against #{required_sats} sats required"
+        transaction.outputs.each_with_index do |output, i|
+          script_match = output.locking_script == expected_script
+          sats_match = output.satoshis >= required_sats
+          logger.info "[brc105]   output[#{i}]: #{output.satoshis} sats, " \
+                      "script=#{output.locking_script.to_hex[0..15]}... " \
+                      "script_match=#{script_match} sats_match=#{sats_match}"
+        end
+      end
+
+      def log_settlement_success(transaction, paid_sats, required_sats)
+        logger.info "[brc105] Settlement OK: txid=#{transaction.txid_hex} " \
+                    "paid=#{paid_sats} required=#{required_sats}"
       end
 
-      def build_settlement_result(transaction)
+      def build_settlement_result(transaction, paid_sats)
         receipt = {
           "success" => true,
           "transaction" => transaction.txid_hex,
           "network" => NETWORK
         }
         SettlementResult.new(
-          receipt_headers: { "x-bsv-payment-result" => Base64.strict_encode64(JSON.generate(receipt)) },
+          receipt_headers: {
+            "x-bsv-payment-satoshis-paid" => paid_sats.to_s,
+            "x-bsv-payment-result" => Base64.strict_encode64(JSON.generate(receipt))
+          },
           txid: transaction.txid_hex,
           network: NETWORK
         )

data/lib/x402/bsv/pay_gateway.rb

@@ -44,15 +44,29 @@ module X402
         @txid_store = txid_store
       end
 
+      # Build a 402 challenge with Coinbase v2 +Payment-Required+ header.
+      #
+      # @param rack_request [Rack::Request]
+      # @param route [X402::Configuration::Route]
+      # @return [Hash] challenge headers
       def challenge_headers(rack_request, route)
         challenge = build_challenge(rack_request, route)
         { "Payment-Required" => Base64.strict_encode64(JSON.generate(challenge)) }
       end
 
+      # @return [Array<String>] proof header names this gateway responds to
       def proof_header_names
         ["Payment-Signature"]
       end
 
+      # Verify and broadcast a Coinbase v2 payment.
+      #
+      # @param _header_name [String] which proof header matched
+      # @param proof_payload [String] base64-encoded payment payload
+      # @param rack_request [Rack::Request]
+      # @param route [X402::Configuration::Route]
+      # @return [SettlementResult]
+      # @raise [VerificationError] on invalid payment, insufficient amount, or broadcast failure
       def settle!(_header_name, proof_payload, rack_request, route)
         required_sats = route.resolve_amount_sats
         payload = decode_payment_payload(proof_payload)

data/lib/x402/bsv/prefix_store.rb

@@ -41,6 +41,8 @@ module X402
 
         # Record a prefix as issued.
         #
+        # @param prefix [String] hex derivation prefix
+        # @return [void]
         # @raise [StoreFullError] if max_issued unconsumed prefixes are held
         def store!(prefix)
           @monitor.synchronize do
@@ -53,6 +55,9 @@ module X402
         end
 
         # Non-binding read: returns true if the prefix was issued and not yet consumed.
+        #
+        # @param prefix [String] hex derivation prefix
+        # @return [Boolean]
         def valid?(prefix)
           @monitor.synchronize do
             entry = @prefixes[prefix]
@@ -62,6 +67,9 @@ module X402
 
         # Atomically mark a prefix as consumed. Returns false if already consumed,
         # unknown, or expired.
+        #
+        # @param prefix [String] hex derivation prefix
+        # @return [Boolean] true if successfully consumed, false if replay/unknown/expired
         def consume!(prefix)
           @monitor.synchronize do
             entry = @prefixes[prefix]

data/lib/x402/bsv/proof_gateway.rb

@@ -35,6 +35,12 @@ module X402
         @arc_client = arc_client
       end
 
+      # Build a 402 challenge with merkleworks +X402-Challenge+ header.
+      #
+      # @param rack_request [Rack::Request]
+      # @param route [X402::Configuration::Route]
+      # @return [Hash] challenge headers
+      # @raise [ConfigurationError] if route uses callable amount_sats (fiat pricing)
       def challenge_headers(rack_request, route)
         if route.amount_sats.respond_to?(:call)
           raise ConfigurationError,
@@ -44,10 +50,19 @@ module X402
         { "X402-Challenge" => challenge.to_header }
       end
 
+      # @return [Array<String>] proof header names this gateway responds to
       def proof_header_names
         ["X402-Proof"]
       end
 
+      # Verify a merkleworks x402 proof against the challenge and check mempool.
+      #
+      # @param _header_name [String] which proof header matched
+      # @param proof_payload [String] base64url-encoded proof
+      # @param rack_request [Rack::Request]
+      # @param route [X402::Configuration::Route]
+      # @return [SettlementResult]
+      # @raise [VerificationError] on invalid proof, binding mismatch, or mempool failure
       def settle!(_header_name, proof_payload, rack_request, route)
         required_sats = route.resolve_amount_sats
         proof = Proof.from_header(proof_payload)

data/lib/x402/configuration.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module X402
+  # DSL for configuring X402 middleware, gateways, and protected routes.
+  #
+  # @example Minimal configuration
+  #   X402.configure do |config|
+  #     config.domain = "api.example.com"
+  #     config.server_wif = ENV["SERVER_WIF"]
+  #     config.arc_url = "https://arc.taal.com"
+  #     config.enable :pay_gateway
+  #     config.protect method: :GET, path: "/api/expensive", amount_sats: 100
+  #   end
   class Configuration
     # Route holds a raw +amount_sats+ that may be an Integer or a callable.
     # The +resolve_amount_sats+ method evaluates callables at access time,
@@ -37,15 +47,28 @@ module X402
 
     attr_accessor :domain, :payee_locking_script_hex, :gateways,
                   :arc_url, :arc_api_key, :arc_client, :server_wif,
-                  :exchange_rate_provider
+                  :exchange_rate_provider, :logger
     attr_reader :routes, :gateway_specs
 
     def initialize
       @routes = []
       @gateways = []
       @gateway_specs = []
+      @logger = default_logger
     end
 
+    private
+
+    def default_logger
+      require "logger"
+      logger = ::Logger.new($stderr)
+      logger.formatter = proc { |_sev, _time, _prog, msg| "#{msg}\n" }
+      logger.level = ::Logger::DEBUG
+      logger
+    end
+
+    public
+
     # Record a gateway to be constructed later during +validate!+.
     #
     # @param name [Symbol] registered gateway name (e.g. +:pay_gateway+)
@@ -114,6 +137,13 @@ module X402
       end
     end
 
+    # Validate the configuration and construct gateways from specs.
+    #
+    # Called automatically at the end of +X402.configure+. Builds gateways
+    # from +enable+ specs, validates all constraints, and emits operational
+    # warnings for development defaults.
+    #
+    # @raise [ConfigurationError] if required fields are missing or invalid
     def validate!
       raise ConfigurationError, "domain is required" if domain.nil? || domain.empty?
 
@@ -140,9 +170,9 @@ module X402
       end
       return unless needs_warning
 
-      warn "[x402] challenge_secret is auto-generated. " \
-           "In-flight challenges will fail after process restart. " \
-           "Set challenge_secret: explicitly for production."
+      logger.warn "[x402] challenge_secret is auto-generated. " \
+                  "In-flight challenges will fail after process restart. " \
+                  "Set challenge_secret: explicitly for production."
     end
 
     def warn_in_memory_prefix_store!
@@ -151,9 +181,9 @@ module X402
       end
       return unless needs_warning
 
-      warn "[x402] BRC105Gateway using in-memory PrefixStore. " \
-           "No replay protection across processes. " \
-           "Use a shared backend (Redis) for multi-process deployments."
+      logger.warn "[x402] BRC105Gateway using in-memory PrefixStore. " \
+                  "No replay protection across processes. " \
+                  "Use a shared backend (Redis) for multi-process deployments."
     end
 
     def validate_gateways!

data/lib/x402/middleware.rb

@@ -4,11 +4,30 @@ require "rack"
 require "json"
 
 module X402
+  # Pure Rack dispatcher for payment-gated HTTP.
+  #
+  # The middleware has no blockchain knowledge — it matches routes, issues
+  # payment challenges by polling configured gateways, and dispatches proofs
+  # to the matching gateway for settlement.
+  #
+  # @example config.ru
+  #   X402.configure do |config|
+  #     config.domain = "api.example.com"
+  #     config.server_wif = ENV["SERVER_WIF"]
+  #     config.arc_url = "https://arc.taal.com"
+  #     config.enable :pay_gateway
+  #     config.protect method: :GET, path: "/api/expensive", amount_sats: 100
+  #   end
+  #
+  #   use X402::Middleware
   class Middleware
+    # @param app [#call] next Rack app in the middleware stack
     def initialize(app)
       @app = app
     end
 
+    # @param env [Hash] Rack environment
+    # @return [Array(Integer, Hash, Array)] Rack response triple
     def call(env)
       request = Rack::Request.new(env)
       config = X402.configuration
@@ -17,12 +36,21 @@ module X402
       # Unprotected route — pass through
       return @app.call(env) unless route
 
+      log = config.logger
+      log.info "[x402] #{request.request_method} #{request.path_info} " \
+               "— protected route, #{route.resolve_amount_sats} sats"
+
+      # BRC-104 §6.2: extract client identity key from x-bsv-auth-identity-key
+      extract_brc103_identity_key!(env, log)
+
       # Check for a proof/payment header from any gateway
       gateway, header_name, proof_payload = detect_proof(env, config)
 
       if gateway
-        settle_and_forward(env, gateway, header_name, proof_payload, request, route)
+        log.info "[x402] Proof header #{header_name} detected — dispatching to #{gateway.class.name}"
+        settle_and_forward(env, gateway, header_name, proof_payload, request, route, log)
       else
+        log.info "[x402] No proof header — issuing 402 challenge"
         issue_challenge(request, route, config)
       end
     end
@@ -40,6 +68,11 @@ module X402
       nil
     end
 
+    # Challenge response body follows BRC-105 §6.2 format.
+    # Settlement errors (e.g. underpayment 402, bad request 400) use the
+    # generic {"error": reason} shape via error_response — these are
+    # distinct: the challenge tells the client what to pay, whereas a
+    # settlement error explains why a submitted payment was rejected.
     def issue_challenge(request, route, config)
       headers = { "content-type" => "application/json" }
 
@@ -49,13 +82,20 @@ module X402
         end
       end
 
-      body = JSON.generate({ error: "Payment Required" })
+      body = JSON.generate(
+        status: "error",
+        code: "ERR_PAYMENT_REQUIRED",
+        satoshisRequired: route.resolve_amount_sats,
+        description: "A BSV payment is required to access this resource."
+      )
       [402, headers, [body]]
     end
 
-    def settle_and_forward(env, gateway, header_name, proof_payload, request, route)
+    def settle_and_forward(env, gateway, header_name, proof_payload, request, route, log)
       result = gateway.settle!(header_name, proof_payload, request, route)
 
+      log.info "[x402] Settlement OK — txid=#{result.txid}"
+
       status, headers, body = @app.call(env)
 
       # Merge any receipt headers from the gateway
@@ -67,10 +107,13 @@ module X402
 
       [status, headers, body]
     rescue X402::VerificationError => e
+      log.warn "[x402] Settlement failed: #{e.status} #{e.reason}"
       error_response(e.status, e.reason)
     rescue X402::Error => e
+      log.warn "[x402] Error: #{e.message}"
       error_response(400, e.message)
-    rescue StandardError
+    rescue StandardError => e
+      log.error "[x402] Unexpected error: #{e.class}: #{e.message}"
       error_response(500, "internal error")
     end
 
@@ -79,6 +122,29 @@ module X402
       [status, { "content-type" => "application/json" }, [body]]
     end
 
+    # BRC-104 §6.2: x-bsv-auth-identity-key carries the client's public
+    # identity key (33-byte compressed secp256k1 pubkey, hex). Populate
+    # brc103.identity_key in the Rack env so gateways can use it as the
+    # counterparty in BRC-42 key derivation.
+    #
+    # NOTE: This is the CLAIMED identity key — not authenticated. BRC-103
+    # signature verification must occur in a separate middleware if identity
+    # assertions are required for authorisation decisions.
+    #
+    # Does not overwrite an identity key already set by upstream middleware
+    # (e.g. a BRC-103/104 auth layer that has verified the signature).
+    def extract_brc103_identity_key!(env, log)
+      return if env["brc103.identity_key"].is_a?(String) && !env["brc103.identity_key"].empty?
+
+      key = env["HTTP_X_BSV_AUTH_IDENTITY_KEY"]
+      if key && !key.empty?
+        log.info "[x402] Client identity key: #{key[0..15]}..."
+        env["brc103.identity_key"] = key.downcase
+      else
+        log.debug "[x402] No x-bsv-auth-identity-key header"
+      end
+    end
+
     def rack_header_key(http_header_name)
       "HTTP_#{http_header_name.upcase.tr("-", "_")}"
     end

data/lib/x402/payment_observer.rb

@@ -55,6 +55,8 @@ module X402
       @on_payment = on_payment
     end
 
+    # @param env [Hash] Rack environment
+    # @return [Array(Integer, Hash, Array)] Rack response triple (always passes through)
     def call(env)
       observe_payment(env)
       @app.call(env)
@@ -129,8 +131,11 @@ module X402
 
     # Built-in extractor for the Coinbase v2 envelope format.
     # Decodes +Base64(JSON({ payload: { rawtx: "hex" } }))+.
-    # Returns a +BSV::Transaction::Transaction+ or +nil+.
+    #
+    # @see PaymentObserver extractor: parameter
     class CoinbaseV2Extractor
+      # @param proof_payload [String] raw proof header value
+      # @return [BSV::Transaction::Transaction, nil] parsed transaction or nil on failure
       def call(proof_payload)
         json = Base64.strict_decode64(proof_payload)
         payload = JSON.parse(json)
@@ -146,11 +151,16 @@ module X402
 
     # Built-in recogniser for a single static payee address.
     # Used when +payee_locking_script_hex+ is provided without a custom recogniser.
+    #
+    # @see PaymentObserver recogniser: parameter
     class StaticRecogniser
+      # @param payee_locking_script_hex [String] hex-encoded locking script to match
       def initialize(payee_locking_script_hex)
         @payee_hex = ::BSV::Script::Script.from_hex(payee_locking_script_hex).to_hex
       end
 
+      # @param locking_script_hex [String] hex-encoded locking script to test
+      # @return [Boolean] true if the script matches the configured payee
       def ours?(locking_script_hex)
         locking_script_hex == @payee_hex
       end

data/lib/x402/settlement_worker.rb

@@ -45,6 +45,10 @@ module X402
       @queue.push(tx_binary)
     end
 
+    # Drain the queue and stop the background thread.
+    # Safe to call when no thread has started (no-op).
+    #
+    # @return [void]
     def stop
       thread_to_join = nil
       @mutex.synchronize do

data/lib/x402/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module X402
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/mkdocs.yml

@@ -0,0 +1,68 @@
+site_name: x402-rack
+site_description: Rack middleware for payment-gated HTTP using BSV
+site_url: https://sgbett.github.io/x402-rack/
+repo_url: https://github.com/sgbett/x402-rack
+repo_name: sgbett/x402-rack
+
+theme:
+  name: material
+  palette:
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - content.code.copy
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - minify:
+      minify_html: true
+
+nav:
+  - Home: index.md
+  - Architecture: architecture.md
+  - Ecosystem: ecosystem.md
+  - Schemes:
+      - BSV-pay: schemes/bsv-pay.md
+      - BSV-proof: schemes/bsv-proof.md
+      - BRC-105: schemes/brc-105.md
+  - Process Flows:
+      - PayGateway: process-flow/pay-gateway.md
+      - ProofGateway: process-flow/proof-gateway.md
+      - BRC105Gateway: process-flow/brc105-gateway.md
+  - Operations:
+      - Deployment: operations/deployment.md
+      - Performance: operations/performance.md
+      - Treasury: operations/treasury.md
+  - Client Integration: client-integration.md
+  - Security: security.md
+  - API Reference: reference/index.md

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: x402-rack
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: exe
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -91,6 +91,7 @@ files:
 - ".claude/plans/20260326-rack-stack-architecture.md"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CLAUDE.md
 - DESIGN.md
@@ -100,12 +101,14 @@ files:
 - docs/architecture.md
 - docs/client-integration.md
 - docs/ecosystem.md
+- docs/index.md
 - docs/operations/deployment.md
 - docs/operations/performance.md
 - docs/operations/treasury.md
 - docs/process-flow/brc105-gateway.md
 - docs/process-flow/pay-gateway.md
 - docs/process-flow/proof-gateway.md
+- docs/requirements.txt
 - docs/schemes/brc-105.md
 - docs/schemes/bsv-pay.md
 - docs/schemes/bsv-proof.md
@@ -130,6 +133,7 @@ files:
 - lib/x402/settlement_worker.rb
 - lib/x402/verification/protocol_checks.rb
 - lib/x402/version.rb
+- mkdocs.yml
 - sig/x402.rbs
 homepage: https://github.com/sgbett/x402-rack
 licenses: