blockchain0x-x402 0.0.1.alpha.0 → 0.0.1.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be9ad30aa23e7e4d44c0dd712254925bb187f4f0c78567aec39c7ea3d4f98587
-  data.tar.gz: 22a5ab6a9635274a08a72dfe3f6fd0f06ecadbcdaf0b1ef05b849673fe5355df
+  metadata.gz: ee6cf734c4809fd53f64cb3a26a1f07710bd0d502008bb07e178f8c37b83bd5f
+  data.tar.gz: 9dfbf939eaa222810a74cc6cf502a5af8958077147843b270a15011e73ae7297
 SHA512:
-  metadata.gz: 35deca80a3287f50c577ac6935a83be33d39268af3fc008972c3d55154d90041a2e0bcca4082689b13b6e0c1f42e0c8d63c4f5aaba9895afe1ce2fe8fd6694b0
-  data.tar.gz: 385941f182db7f338f0cd26b9a63ab8c90a368535f2323ee869cfc1b7d39acfdaed09e08a2cef83fa95c0712403274b15f7f6cff3e083ddd8acce7bcaa3a6592
+  metadata.gz: 59eb62699d8f3941e2c9edd2f40051a5e8015a4001a42ae10c8cd83419a867809b426c8baaef47100bfcee3aea15023c1e99373437461cca6b9fcb903f4ec728
+  data.tar.gz: fb89d30a00d8ac9fd262846d8ff3ca300408ce45bafa74927477f93e2a9688a2b7a1afa1060f1d0e178ab87a0f767ecdb6fb374ab2dd216cf03d8b85a0a49a95

data/lib/blockchain0x_x402/client.rb

@@ -21,6 +21,14 @@
 # wrapper propagates that response unchanged so the caller can
 # decide whether to loop or surface to the user.
 #
+# Spend policy (sub-plan 27.1 A6): the 402 challenge is
+# ATTACKER-CONTROLLED input. Callers MUST set `max_amount_wei`
+# (and should set `allowed_pay_to`) so a malicious or compromised
+# seller cannot drain the session allowance by quoting an
+# arbitrary amount/recipient. The wrapper also enforces the
+# requirement's maxAgeSeconds and refuses 402s that match no
+# known network instead of guessing.
+#
 # The `sdk` is duck-typed: any object responding to
 # `network`, `payments_create(args)`, and `transactions_get(id)`
 # works. Tests mock the surface; production passes a
@@ -39,24 +47,40 @@ module Blockchain0xX402
 
     # @param sdk [#network, #payments_create, #transactions_get]
     # @param agent_id [String] wallet that funds the on-chain payment
+    # @param max_amount_wei [String, nil] spend ceiling in 6-dp USDC base
+    #   units (27.1 A6). SET THIS - a 402 quoting more is refused with
+    #   ClientError 'amount_over_cap' before any payment is created.
+    # @param allowed_pay_to [Array<String>, nil] optional recipient
+    #   allowlist (27.1 A6); compared case-insensitively.
     # @param confirm_timeout_seconds [Integer]
     # @param confirm_poll_seconds    [Float]
     # @param connection [Faraday::Connection, nil] test seam
     # @param sleep_proc [#call, nil] test seam for the poll loop
+    # @param now_proc [#call, nil] test seam for the maxAgeSeconds clock
     def initialize(
       sdk:,
       agent_id:,
+      max_amount_wei: nil,
+      allowed_pay_to: nil,
       confirm_timeout_seconds: DEFAULT_CONFIRM_TIMEOUT_SECONDS,
       confirm_poll_seconds: DEFAULT_CONFIRM_POLL_SECONDS,
       connection: nil,
-      sleep_proc: nil
+      sleep_proc: nil,
+      now_proc: nil
     )
+      if !max_amount_wei.nil? && !max_amount_wei.to_s.match?(/\A[0-9]+\z/)
+        raise ArgumentError, 'max_amount_wei must be an integer string of 6-dp USDC base units'
+      end
+
       @sdk = sdk
       @agent_id = agent_id
+      @max_amount_wei = max_amount_wei&.to_s
+      @allowed_pay_to = allowed_pay_to&.map(&:downcase)
       @confirm_timeout = confirm_timeout_seconds
       @confirm_poll = confirm_poll_seconds
       @conn = connection || Faraday.new
       @sleep = sleep_proc || Kernel.method(:sleep)
+      @now = now_proc || method(:monotonic_now)
     end
 
     # Perform an HTTP request that handles 402 automatically.
@@ -70,7 +94,11 @@ module Blockchain0xX402
       return first unless first.status == 402
 
       spec = Wire.parse_402_response(first)
+      challenge_at = @now.call
       requirement = pick_requirement(spec.accepts)
+      # 27.1 A6: the 402 is attacker-controlled input - enforce the
+      # caller's spend policy BEFORE any payment is created.
+      enforce_spend_policy(requirement)
       payment = @sdk.payments_create(
         agent_id: @agent_id,
         to: requirement.pay_to_address,
@@ -80,6 +108,18 @@ module Blockchain0xX402
       raise ClientError.new('chain_failed', 'payments_create did not return an id.') if payment_id.nil?
 
       confirmed = wait_for_confirmation(payment_id)
+      # 27.1 A6: a proof that confirmed after the requirement's
+      # maxAgeSeconds window is refused client-side, not presented.
+      if requirement.max_age_seconds
+        elapsed = @now.call - challenge_at
+        if elapsed > requirement.max_age_seconds
+          raise ClientError.new(
+            'stale_challenge',
+            "challenge expired: confirmation took #{elapsed.round}s, " \
+              "maxAgeSeconds is #{requirement.max_age_seconds}.",
+          )
+        end
+      end
 
       header = Wire.build_payment_header(
         Wire::ExactUsdcPayment.new(
@@ -122,6 +162,24 @@ module Blockchain0xX402
       )
     end
 
+    # 27.1 A6: spend-policy gate, evaluated before any payment exists.
+    def enforce_spend_policy(requirement)
+      if @max_amount_wei && Integer(requirement.amount_wei_usdc, 10) > Integer(@max_amount_wei, 10)
+        raise ClientError.new(
+          'amount_over_cap',
+          "402 quotes #{requirement.amount_wei_usdc} wei USDC, above the " \
+            "configured max_amount_wei #{@max_amount_wei}.",
+        )
+      end
+      return unless @allowed_pay_to && !@allowed_pay_to.include?(requirement.pay_to_address.downcase)
+
+      raise ClientError.new(
+        'recipient_not_allowed',
+        "402 pay-to address #{requirement.pay_to_address} is not in the " \
+          'configured allowed_pay_to list.',
+      )
+    end
+
     def wait_for_confirmation(payment_id)
       deadline = monotonic_now + @confirm_timeout
       last = nil

data/lib/blockchain0x_x402/errors.rb

@@ -35,8 +35,14 @@ module Blockchain0xX402
   # challenge. Codes:
   #
   #   no_matching_requirement  - no accepts entry matched the SDK network
+  #                              (or the network is unknown; sub-plan 27.1
+  #                              A6 - a refusal, never an accepts[0] guess)
   #   settlement_timeout       - on-chain payment did not confirm in budget
   #   chain_failed             - payment status flipped to failed
+  #   amount_over_cap          - 402 quoted above max_amount_wei (27.1 A6)
+  #   recipient_not_allowed    - payToAddress outside allowed_pay_to (27.1 A6)
+  #   stale_challenge          - confirmation landed after the requirement's
+  #                              maxAgeSeconds window (27.1 A6)
   class ClientError < Error
   end
 end

data/lib/blockchain0x_x402/version.rb

@@ -5,5 +5,5 @@
 # frozen_string_literal: true
 
 module Blockchain0xX402
-  VERSION = '0.0.1.alpha.0'
+  VERSION = '0.0.1.alpha.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blockchain0x-x402
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha.0
+  version: 0.0.1.alpha.1
 platform: ruby
 authors:
 - Blockchain0x
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-30 00:00:00.000000000 Z
+date: 2026-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -30,6 +30,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -65,10 +79,10 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://blockchain0x.com
-  source_code_uri: https://github.com/Tosh-Labs/blockchain0x-app/tree/dev/packages/sdk-ruby-x402
-  bug_tracker_uri: https://github.com/Tosh-Labs/blockchain0x-app/issues
+  source_code_uri: https://github.com/tosh-labs/blockchain0x-app/tree/dev/packages/sdk-ruby-x402
+  bug_tracker_uri: https://github.com/tosh-labs/blockchain0x-app/issues
   documentation_uri: https://docs.blockchain0x.com
-  changelog_uri: https://github.com/Tosh-Labs/blockchain0x-x402-ruby/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/tosh-labs/blockchain0x-x402-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []