rail0-sdk 1.6.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e046261654c0f0d93915dd0ac7003e78f224115748e697581cac6020c4ea4003
-  data.tar.gz: f9fea94c35a6b996732e0bbdc538361a229134edaa4f52bc6a010e1dfd55b871
+  metadata.gz: 5d88d3da009d4c04853e8fb794eba655913763a1391c6e0bd6915bda6cb68d36
+  data.tar.gz: 5cc37022ce71f950c6b11dcf421902518b63caebfd54a13f78eaf909a7eef39c
 SHA512:
-  metadata.gz: dcb35d580188aef4a5e6b36878e6e8b3da40dddd671a792eb3275f4baad286636ec6f00e6284d1a0263c6ec764d539e17d8c85ea1904b77f3f1326e8929174fd
-  data.tar.gz: 592f3db30a8c9ecdc755f5b64e9dc0a69166ca73f6b51efcae2c348fb28e60d39b148b41b3cd54015012837c7a8987583d3bc6621f6ef82a4bca3e8b14381526
+  metadata.gz: 2512e0a842d7d76749dc4028a0c1d2590b7fe1dd4e95676572a39aa8c41fa9a882c2e4a534e85080f0fe8089c8001c6f2101ff4b9fb7ab9f4e2cc9d7e6d35d62
+  data.tar.gz: 7b569639525815722a586f308d45ebc67c964cbd4f6f1ae4c5bac4a8c5a731589b03dffebcfcdb375e3a265f9f1143b52162d5e8685de591e39a364de3257cf8

data/README.md

@@ -78,7 +78,9 @@ payment = client.payments.create(
 rail0_id = payment[:rail0_id]
 
 # 2. Payer signs the EIP-3009 payload off-chain and deposits the signature.
-sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, payment[:signing_payload])
+#    payment: is what the authorization is CHECKED against before the key signs it
+#    (see "What sign_signing_payload verifies").
+sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], BUYER_PRIVATE_KEY, payment: payment)
 client.payments.sign(rail0_id, { signature: sig.to_hex })
 
 # 3. Payee prepares + broadcasts the on-chain authorize tx (signs it locally).
@@ -126,21 +128,54 @@ otherwise have that key sign anything — an `approve(spender, MAX)` on the toke
 `payment:` (the record from `payments.get`) and `operation:`, `sign_transaction` checks
 the transaction **before** the key touches it, against data you already hold (no extra
 request): `value` is zero (every RAIL0 operation is value-0), `chain_id` is the
-payment's chain, `from` is your key's address, `to` is the payment's `rail0_contract`,
+payment's chain, `from` is your key's address, `to` is an address and is the payment's
+`rail0_contract` (an empty or missing `to` — which would sign a contract creation — is
+always refused, even by the deprecated blind form),
 the 4-byte selector is the RAIL0 function for `operation:` (the selectors are derived
 from the contract's function signatures, `Rail0::TxVerify::SELECTORS`, and pinned
 against its ABI in the spec suite), the first calldata word is the payment's `rail0_id`,
 and — for `capture` and `refund` — the amount word equals `amount:` scaled by the
 payment's `decimals`. The first mismatch raises `Rail0::TxVerify::RefusedSignature`
 ("refusing to sign: …", naming the field) and no signature is produced. It fails closed:
-a capture/refund with no `amount:`, or a payment with unknown `decimals`, is refused
-rather than skipped. `to` is a consistency check only — the address comes from the same
+a capture/refund with no `amount:`, or a payment with no `rail0_contract` or unknown
+`decimals`, is refused rather than skipped. `to` is a consistency check only — the address comes from the same
 gateway — which is why the calldata binding to this payment's id and operation is what
 closes a swapped transaction. Calling `sign_transaction` without `payment:` still signs
 blindly and is **deprecated** (a `:deprecated`-category warning; shown with
 `-W:deprecated`). `Rail0::TxVerify.verify` runs the check on its own, for a signer that
 is not a local key.
 
+**What `sign_signing_payload` verifies, and why.** The EIP-3009 authorization the payer
+signs after `create` (and the payee signs in refund phase 1) is the more dangerous of the
+two artifacts: the **token** honours it on its own, with no RAIL0 involvement, for up to
+its `value` — so an endpoint that answered with `{from: you, to: attacker, value: your
+whole balance}` used to get exactly that signed. `sign_signing_payload(signing_payload,
+key, payment:, amount: nil)` checks it first. The typed-data envelope: `primaryType` is
+`ReceiveWithAuthorization` (authorize/charge on v1.4.0+ deployments, and every refund) or
+`TransferWithAuthorization` (authorize/charge on v1.1.0–v1.3.x); `types[primaryType]` is
+**exactly** the EIP-3009 struct — `address from, address to, uint256 value, uint256
+validAfter, uint256 validBefore, bytes32 nonce`, same names, types and order;
+`types.EIP712Domain`, when present, is exactly `string name, string version, uint256
+chainId, address verifyingContract`; and `types` defines nothing else (a local key hashes
+with fixed typehashes, but a browser wallet hashes whatever `types` says, so this is what
+lets `PayloadVerify.verify` guard an `eth_signTypedData_v4` call). Then, against data you
+already hold: `message.from` is your key's address, `domain.chainId` the payment's `chain_id`,
+`domain.verifyingContract` the payment's `token`, `message.to` its `rail0_contract`, and
+`message.value` **exactly** the amount — `amount:` scaled by the payment's `decimals` when
+you pass one (a refund), otherwise the payment's own base-unit `amount` (a created
+payment). The first mismatch raises `Rail0::TxVerify::RefusedSignature` ("refusing to
+sign: …", naming the field) and nothing is signed. It fails closed: a payment record
+missing `chain_id`, `token`, `rail0_contract` or an amount to compare is refused, and so
+are unknown `decimals` and an amount finer than the token's. The payload is still signed
+verbatim (typehash from its own `primaryType`). Not checked, as in the CLI: the validity
+window and `message.nonce` (recomputing it needs the deployment's `VERSION()`, which no
+payment response carries), and `to` and the decimals come from the same gateway. The
+residual is an authorization for the right token, chain and signer, for exactly the
+amount you asked. `sign_payload(key, signing_payload)` without `payment:` still signs
+blindly and is **deprecated** (`:deprecated`-category warning); with `payment:` it is
+`sign_signing_payload`. `Rail0::PayloadVerify.verify(signing_payload, payment:, signer:,
+amount: nil)` runs the check on its own.
+
 Wallets that sign **and** broadcast in one step (e.g. MetaMask via
 `eth_sendTransaction`) skip steps 2–3 and report the hash instead:
 
@@ -211,8 +246,8 @@ auth = client.auth.login(private_key: "0x…", domain: "api.rail0.xyz")
 # admin is always a boolean (verify too): true only for an account holding the
 # operator grant, false otherwise (visibility only). account_id/name are nil for an
 # account-less session.
-# login embeds chain_id 1 by default; pass chain_id: to match a gateway whose
-# SIWE_CHAIN_ID policy differs (e.g. login(private_key:, domain:, chain_id: 5042002)).
+# login embeds chain_id 1 by default; the gateway also accepts the id of any chain it
+# has active (GET /blockchains), e.g. login(private_key:, domain:, chain_id: 5042002).
 
 authed = Rail0::Client.new(
   base_url: "https://api.rail0.xyz",
@@ -488,8 +523,11 @@ transactions, so a bulk action can skip busy rows without a `get(id)` each.
 
 ```ruby
 # Phase 1 — amount only → returns a signing payload for the payee to sign.
+#           The authorization is checked against the payment and the refund amount
+#           (payment = client.payments.get(rail0_id)) before the key signs it.
 p1  = client.payments.refund_prepare(rail0_id, amount: "20.00")
-sig = Rail0::Signing.sign_payload(MERCHANT_PRIVATE_KEY, p1[:signing_payload])
+sig = Rail0::Signing.sign_signing_payload(p1[:signing_payload], MERCHANT_PRIVATE_KEY,
+                                          payment: payment, amount: "20.00")
 
 # Phase 2 — amount + signature → returns the unsigned on-chain tx.
 p2  = client.payments.refund_prepare(rail0_id, amount: "20.00", signature: sig.to_hex)
@@ -795,21 +833,29 @@ Requires the `eth` gem. No private key ever leaves your process.
 
 | Method | Use |
 |--------|-----|
-| `sign_payload(signer, signing_payload)` | Sign the EIP-3009 payload from a create/refund response — the recommended path, and the only one that follows the gateway across contract versions |
+| `sign_signing_payload(signing_payload, signer, payment:, amount: nil)` | Verify the EIP-3009 payload from a create/refund response against the payment, then sign it verbatim — the recommended path, and the only one that follows the gateway across contract versions |
+| `sign_payload(signer, signing_payload, payment: nil, amount: nil)` | The same signer; with `payment:` it is `sign_signing_payload`, without it signs blindly (**deprecated**) |
+| `Rail0::PayloadVerify.verify(signing_payload, payment:, signer:, amount: nil)` | The payload pre-sign check on its own — run it before handing the payload to a browser wallet |
 | `sign_transaction(unsigned_transaction, key, payment:, operation:, amount: nil)` | Verify a prepare step's unsigned EIP-1559 transaction against the payment, then sign it; returns the 0x raw tx. Without `payment:` it signs blindly (**deprecated**) |
 | `Rail0::TxVerify.verify(unsigned_transaction, payment:, operation:, amount: nil, signer: nil)` | The pre-sign check on its own — for a signer that is not a local key |
 | `sign_transfer_with_authorization(signer, domain, params)` | Raw EIP-3009 `TransferWithAuthorization` signer, for talking to a token directly |
 
 ```ruby
 require "rail0/signing"
-sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, payment[:signing_payload])
-client.payments.sign(rail0_id, { signature: sig.to_hex })
+payment = client.payments.create(chain_id: 84532, mode: "authorize", amount: "50.00", token: TOKEN,
+                                 payer: BUYER, payee: MERCHANT)
+sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], BUYER_PRIVATE_KEY, payment: payment)
+client.payments.sign(payment[:rail0_id], { signature: sig.to_hex })
+# A hostile payload — another `to`, a larger `value`, another token — raises instead:
+#   Rail0::TxVerify::RefusedSignature: refusing to sign: the authorization is for
+#   999999999999 base units but you asked for 50000000
 ```
 
-**The gateway builds the payload; you sign it verbatim.** `sign_payload` takes the
+**The gateway builds the payload; you sign it verbatim.** `sign_signing_payload` takes the
 typehash from the payload's `primaryType` and every field from its `message` — only
 the gateway knows which contract version a payment lives on, and the version selects
-the typehash, the EIP-712 domain and the field layout. An unrecognised `primaryType`
+the typehash and the EIP-712 domain (the field layout is EIP-3009's own, the same on
+every version, which is why the check pins it). An unrecognised `primaryType`
 raises rather than falling back, because a guessed typehash yields a *valid*
 signature over the wrong digest, which fails only on-chain, after gas.
 
@@ -818,20 +864,24 @@ digest from a payment record. They raise with a pointer here.
 
 ### Signing without a raw key
 
-`sign_payload` and `sign_transfer_with_authorization` accept a private-key String,
-an `Eth::Key`, or **any object responding to `#sign(digest)`** that returns a
-65-byte hex signature — a KMS or HSM client, a remote signer, a hardware-wallet
+`sign_signing_payload`, `sign_payload` and `sign_transfer_with_authorization` accept a
+private-key String, an `Eth::Key`, or **any object responding to `#sign(digest)`** that
+returns a 65-byte hex signature — a KMS or HSM client, a remote signer, a hardware-wallet
 bridge. The SDK builds the EIP-712 digest and hands only that over, so the secret
 need never be materialised as a String in your process:
 
 ```ruby
 class KmsSigner
   def sign(digest) = MyKms.sign(key_id: KEY_ID, digest: digest)  # -> "0x…" (65 bytes)
+  def address = KMS_KEY_ADDRESS  # what message.from is checked against
 end
 
-sig = Rail0::Signing.sign_payload(KmsSigner.new, payment[:signing_payload])
+sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], KmsSigner.new, payment: payment)
 ```
 
+The checked form needs the signer's address to compare with the authorization's `from`,
+so a custom signer must also respond to `#address` (an `ArgumentError` says so otherwise).
+
 `sign_transaction` is narrower on purpose: `Eth::Tx#sign` derives an EIP-155 `v`
 from the chain id, so it needs a full `Eth::Key` (a String or an `Eth::Key`), not a
 bare digest signer.
@@ -977,6 +1027,8 @@ lib/rail0/
   backoff.rb           Rail0::Backoff — retry delays and 429 jitter
   webhook_signature.rb Rail0::WebhookSignature — delivery verification
   signing.rb           EIP-3009 + EIP-1559 signing (requires 'eth')
+  tx_verify.rb         Rail0::TxVerify — pre-sign check of an unsigned transaction
+  payload_verify.rb    Rail0::PayloadVerify — pre-sign check of an EIP-3009 signing payload
   stablecoins.rb       stablecoin address registry
   dispute_reasons.rb   generated Rail0::DisputeReasons — the dispute-reason dictionary
   types.rb             generated Struct docs of the gateway schema (reference only)

data/lib/rail0/error_hints.rb

@@ -23,11 +23,12 @@ module Rail0
     "signer_mismatch" => "the signature recovers to a different wallet than the one that must sign — the payment's payer/payee, or at POST /claim the wallet the onboarding request names",
     # The SIWE BINDING failures, split out of signer_mismatch so a failed login says
     # WHICH part of the proof did not bind (#216). None names the server's own
-    # expectation: that endpoint is unauthenticated, so echoing the allow-list or the
-    # expected chain id would turn every hint into a probe.
+    # expectation: that endpoint is unauthenticated, so echoing the allow-list would
+    # turn every hint into a probe. siwe_chain_mismatch may point at GET /blockchains:
+    # the accepted chain ids (1 plus every active catalog chain) are public there anyway.
     "siwe_domain_not_allowed" => "sign with the origin the front-end is served from, and have it added to the gateway's SIWE domain allow-list",
     "siwe_uri_mismatch" => "the message's uri host must equal its own domain",
-    "siwe_chain_mismatch" => "use the chain id the client library sends - this login is off-chain and nominal",
+    "siwe_chain_mismatch" => "sign with chain id 1 (what the SDK's signing helpers send) or the id of a chain the gateway has active (GET /blockchains) - usually a hand-built message or a wallet on an unsupported or deactivated network",
     "siwe_proof_expired" => "get a fresh nonce and sign again",
     # Address-wide, not one token: "sign in again", not "that token is dead".
     "sessions_revoked" => "every session issued before this address's revoke-all cutoff is refused - sign in again",
@@ -79,6 +80,20 @@ module Rail0
     "unknown_token" => "the token isn't configured on this chain",
     "no_active_contract" => "no active RAIL0 contract on that chain",
     "missing_param" => "a required parameter is missing from the request",
+    # Ported from rail0-go / rail0-ts, which carried these five and this table did not.
+    "validation_failed" => "a parameter is invalid — the error detail names the offending field",
+    "invalid_sort" => "that field cannot be sorted on — the error detail names the allowed set",
+    "rate_limited" => "rate limit reached — wait for Retry-After (the time left in the window) and retry",
+    "event_not_found" => "the reported transaction mined but did not perform this operation on this payment — nothing moved; check the hash and prepare the operation again",
+    "submission_timeout" => "the transaction was not mined in time and was recorded as failed — if it mines later, re-report its hash via the operation's submitted endpoint",
+    # From the gateway's error catalog (lib/rail0/error_catalog.rb).
+    "invalid_signature" => "the signature could not be recovered — it is malformed, truncated or has a bad recovery byte; send the 65-byte 0x hex (r || s || v) the signer produced",
+    "nonce_used" => "that sign-in nonce was already consumed — request a fresh one (auth.nonce); each is single-use",
+    "siwe_purpose_mismatch" => "the signed message's statement is for a different flow — login, wallet registration, account claim and revoke-all each need their own exact statement",
+    "transaction_mismatch" => "the submitted transaction's target, calldata, value or chain differs from the one this operation prepared — sign the prepare's unsigned_transaction unmodified",
+    "signing_payload_unavailable" => "the gateway could not build the payer's authorization payload because a chain read failed — retry in a moment (payments.get returns it once available)",
+    "queue_unavailable" => "the gateway's job queue could not be reached, so nothing was enqueued — retry in a moment",
+    "webhook_limit_reached" => "this account already holds the most webhook subscriptions it may have — delete one, or add topics to an existing subscription",
     # Onboarding: POST /signup and POST /claim (the gateway's onboarding flow).
     # The /admin/onboardings codes (onboarding_not_found, onboarding_completed) are left
     # out: those routes are the console's, not the SDK's. The link codes never say which

data/lib/rail0/payload_verify.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative "tx_verify"
+
+module Rail0
+  # Pre-sign verification of a gateway-built EIP-712 / EIP-3009 +signing_payload+ —
+  # {Rail0::TxVerify}'s counterpart for the authorization rather than the transaction.
+  #
+  # It is the MORE dangerous artifact of the two. A malicious transaction costs gas and
+  # goes through RAIL0; an EIP-3009 authorization is a bearer instrument the TOKEN
+  # honours directly, with no RAIL0 involvement, for up to +message.value+. An endpoint
+  # that answered a refund prepare with +{from: <payee>, to: <attacker>, value: <the
+  # payee's whole balance>}+ used to get exactly that signed by {Signing.sign_payload},
+  # and could replay it against the token.
+  #
+  # Ported from the rail0 CLI's cmd/tx_verify.go (+verifySigningPayload+), which is the
+  # reference for the checks, their order and the wording. In order:
+  #
+  # 1. +message.from+ is the signing key's address — the one comparison whose right-hand
+  #    side is derived locally from the key, so it holds whatever the endpoint claims;
+  # 2. +domain.chainId+ is the payment's +chain_id+;
+  # 3. +domain.verifyingContract+ is the payment's +token+ (for EIP-3009 the domain IS
+  #    the token: this stops an authorization minted against another token the signer
+  #    happens to hold);
+  # 4. +message.to+ is the payment's +rail0_contract+ — a consistency check, the address
+  #    comes from the same gateway;
+  # 5. +message.value+ is EXACTLY the amount asked for, in base units — not a ceiling:
+  #    the gateway asks for the full amount of the operation.
+  #
+  # Before those, the typed-data envelope: +primaryType+ is one of the two EIP-3009
+  # authorization types, +types[primaryType]+ is EXACTLY the EIP-3009 field list (names,
+  # types, order), +types.EIP712Domain+ (when present) is exactly the token domain's
+  # field list, and +types+ defines nothing else. {Signing.sign_payload} hashes with
+  # fixed typehashes and would not notice, but a browser wallet hashes whatever +types+
+  # says — so a caller that verifies here and then hands the payload to
+  # +eth_signTypedData_v4+ needs it.
+  #
+  # The payload is still signed VERBATIM: the typehash comes from its own +primaryType+
+  # and the digest from its own message. This only refuses a message whose fields
+  # contradict what the caller asked for. Like the CLI, it does not check the
+  # validity window, or +message.nonce+ — recomputing the nonce needs the deployment's
+  # VERSION(), which no payment response carries. The bounded residual is an
+  # authorization for the RIGHT token, on the RIGHT chain, from the RIGHT signer, for
+  # EXACTLY the amount asked for.
+  #
+  # FAIL-CLOSED where the CLI is: the amount check never skips (no amount and no stored
+  # base-unit amount, or unknown decimals, refuses). The CLI skips a check whose
+  # expectation it could not resolve; here every expectation comes from the payment
+  # record the caller passes, which always carries chain_id, token and rail0_contract,
+  # so a record missing one of them refuses rather than skipping.
+  #
+  # Loaded by +rail0/signing+ (TxVerify needs the +eth+ gem), never by +require "rail0"+.
+  module PayloadVerify
+    # Verifies +signing_payload+ against +payment+, BEFORE any key touches it. Raises
+    # {Rail0::TxVerify::RefusedSignature} ("refusing to sign: …", naming the field) on
+    # the first mismatch; returns the payload, symbol-keyed, otherwise.
+    #
+    # @param signing_payload [Hash] the +signing_payload+ of a create, get or refund
+    #   prepare response (string or symbol keys)
+    # @param payment [Hash] the payment record: +chain_id+, +token+, +rail0_contract+,
+    #   and +amount+ (base units) or +decimals+ (to scale +amount:+)
+    # @param signer [String] the address of the key about to sign
+    # @param amount [String, nil] the human decimal you asked for (a refund's amount).
+    #   Scaled by the payment's +decimals+. When nil, the payment's own stored +amount+
+    #   (base units) is the expectation — what the payer of a created payment agrees to.
+    # @return [Hash] the payload, symbol-keyed
+    def self.verify(signing_payload, payment:, signer:, amount: nil)
+      sp, domain, message = parse(signing_payload)
+      pay = payment_fields(payment)
+      refuse("cannot check the authorization without the address of the signing key") if blank?(signer)
+
+      check_typed_data(sp[:primaryType], sp[:types])
+      check_from(message[:from], signer.to_s)
+      check_chain(domain[:chainId], pay[:chain_id])
+      check_address(domain[:verifyingContract], pay[:token], "token") do |got, want|
+        "the authorization is against token #{got} but this payment's token is #{want}"
+      end
+      check_address(message[:to], pay[:rail0_contract], "rail0_contract") do |got, want|
+        "the authorization pays #{got} but this payment's RAIL0 contract is #{want}"
+      end
+      check_value(message[:value], expected_base_units(pay, amount))
+      sp
+    end
+
+    def self.parse(signing_payload)
+      refuse("there is no signing payload to check") unless signing_payload.is_a?(Hash)
+      sp = symbolize(signing_payload)
+      domain  = sp[:domain]
+      message = sp[:message]
+      refuse("the signing payload has no domain object") unless domain.is_a?(Hash)
+      refuse("the signing payload has no message object") unless message.is_a?(Hash)
+      [sp, symbolize(domain), symbolize(message)]
+    end
+
+    def self.payment_fields(payment)
+      refuse("cannot check the authorization without the payment it is for") unless payment.is_a?(Hash)
+      symbolize(payment)
+    end
+
+    private_class_method :parse, :payment_fields
+
+    # The EIP-3009 authorization types the gateway emits. Which one a payment needs is the
+    # deployment's contract version, which no payment response carries: 1.4.0 and later
+    # use ReceiveWithAuthorization for authorize/charge, 1.1.0–1.3.x used
+    # TransferWithAuthorization, and refunds are ReceiveWithAuthorization on every
+    # version. So both are accepted and nothing else is.
+    PRIMARY_TYPES = %w[TransferWithAuthorization ReceiveWithAuthorization].freeze
+
+    # The EIP-3009 struct shared by both types: names, types AND order are the typehash.
+    AUTHORIZATION_FIELDS = [
+      %w[from address], %w[to address], %w[value uint256],
+      %w[validAfter uint256], %w[validBefore uint256], %w[nonce bytes32]
+    ].freeze
+
+    # The token's EIP-712 domain, as the gateway declares it and the token hashes it.
+    DOMAIN_FIELDS = [
+      %w[name string], %w[version string], %w[chainId uint256], %w[verifyingContract address]
+    ].freeze
+
+    private_constant :PRIMARY_TYPES, :AUTHORIZATION_FIELDS, :DOMAIN_FIELDS
+
+    # The typed-data envelope: refuses an unknown +primaryType+, a +types[primaryType]+
+    # that differs from the EIP-3009 struct in any name, type or position, an
+    # +EIP712Domain+ that differs from the token domain, or any further type.
+    def self.check_typed_data(primary_type, types)
+      unless PRIMARY_TYPES.include?(primary_type)
+        refuse("the authorization's primaryType #{primary_type.inspect} is not an EIP-3009 authorization type " \
+               "(TransferWithAuthorization or ReceiveWithAuthorization)")
+      end
+      refuse("the signing payload has no types") unless types.is_a?(Hash)
+
+      types = types.transform_keys(&:to_s)
+      extra = types.keys.find { |name| name != primary_type && name != "EIP712Domain" }
+      if extra
+        refuse("the signing payload's types define #{extra.inspect}, which an EIP-3009 authorization does not use")
+      end
+      check_type_fields("types.#{primary_type}", types[primary_type], AUTHORIZATION_FIELDS)
+      check_type_fields("types.EIP712Domain", types["EIP712Domain"], DOMAIN_FIELDS) if types.key?("EIP712Domain")
+    end
+
+    def self.check_type_fields(label, fields, want)
+      return if exact_fields?(fields, want)
+
+      expected = want.map { |name, type| "#{type} #{name}" }.join(",")
+      refuse("#{label} is (#{describe_fields(fields)}) but must be exactly (#{expected})")
+    end
+
+    def self.describe_fields(fields)
+      return (fields.nil? ? "null" : fields.inspect) unless fields.is_a?(Array)
+
+      fields.map { |f| f.is_a?(Hash) ? "#{field_of(f, 'type')} #{field_of(f, 'name')}" : f.inspect }.join(",")
+    end
+
+    def self.exact_fields?(fields, want)
+      fields.is_a?(Array) && fields.size == want.size &&
+        fields.each_with_index.all? do |f, i|
+          f.is_a?(Hash) && f.size == 2 && field_of(f, "name") == want[i][0] && field_of(f, "type") == want[i][1]
+        end
+    end
+
+    # A field entry's +name+ / +type+, whether the payload arrived string- or
+    # symbol-keyed.
+    def self.field_of(field, key)
+      field.key?(key) ? field[key] : field[key.to_sym]
+    end
+
+    private_class_method :check_typed_data, :check_type_fields, :describe_fields, :exact_fields?, :field_of
+
+    # Check 1: from = the key's own address. An absent +from+ is a mismatch, not a skip.
+    def self.check_from(from, signer)
+      return if same_address?(from, signer)
+
+      refuse("the authorization is from #{from} but the signing key is #{signer}")
+    end
+
+    # Check 2. Both sides may arrive as an Integer or a decimal String.
+    def self.check_chain(got, want)
+      refuse("cannot check the authorization's chain without the payment's chain_id") if blank?(want)
+      return if decimal?(got) && decimal?(want) && Integer(got.to_s, 10) == Integer(want.to_s, 10)
+
+      refuse("the authorization is scoped to chain #{got} but this payment is on chain #{want}")
+    end
+
+    # Checks 3 and 4: an address against the payment record's, case-insensitively (the
+    # gateway may return checksummed addresses). The block words the mismatch.
+    def self.check_address(got, want, field)
+      refuse("cannot check the authorization without the payment's #{field}") if blank?(want)
+      return if same_address?(got, want)
+
+      refuse(yield(got, want))
+    end
+
+    # Check 5: exact equality in base units. A value that is not a plain decimal integer
+    # cannot equal one, so it refuses with the same message rather than being coerced
+    # (the signer's +to_i+ would read "1000000abc" as 1000000).
+    def self.check_value(got, want)
+      return if decimal?(got) && Integer(got.to_s, 10) == Integer(want, 10)
+
+      refuse("the authorization is for #{got} base units but you asked for #{want}")
+    end
+
+    private_class_method :check_from, :check_chain, :check_address, :check_value
+
+    # The base-unit amount the authorization must carry. The caller's own +amount:+ is
+    # the trustworthy side, so it wins and is scaled locally by the payment's decimals;
+    # without one, the payment's stored base-unit amount is what is being agreed to.
+    # Either way it never returns nil: the whole guard exists for this comparison.
+    def self.expected_base_units(pay, amount)
+      if blank?(amount)
+        stored = pay[:amount]
+        return stored.to_s if decimal?(stored)
+
+        refuse("cannot check the authorization's amount without an amount: pass amount: " \
+               "or a payment record carrying its base-unit amount")
+      end
+      if pay[:decimals].nil?
+        refuse("the payment's token decimals are unknown, so the authorization's amount cannot be checked " \
+               "(fetch the payment with payments.get first)")
+      end
+      TxVerify.to_base_units(amount.to_s, Integer(pay[:decimals]))
+    end
+
+    private_class_method :expected_base_units
+
+    def self.refuse(message)
+      raise TxVerify::RefusedSignature, "refusing to sign: #{message}"
+    end
+
+    def self.symbolize(hash)
+      hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+    end
+
+    def self.blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def self.decimal?(value)
+      value.is_a?(Integer) ? value >= 0 : value.is_a?(String) && value.match?(/\A\d+\z/)
+    end
+
+    # Both sides must be addresses: two blanks (or two identical non-addresses) are not
+    # a match.
+    def self.same_address?(left, right)
+      TxVerify.address?(left) && TxVerify.address?(right) && left.casecmp(right).zero?
+    end
+
+    private_class_method :refuse, :symbolize, :blank?, :decimal?, :same_address?
+  end
+end

data/lib/rail0/resources/auth.rb

@@ -132,9 +132,9 @@ module Rail0
       #
       # @param private_key [String] 0x-prefixed hex private key of the account wallet.
       # @param domain      [String] Host of the API server (e.g. "api.rail0.xyz").
-      # @param chain_id    [Integer] Chain ID to embed in the SIWE message. Must match
-      #   the gateway's SIWE_CHAIN_ID policy (default 1); override only when the
-      #   gateway is configured with a different login chain.
+      # @param chain_id    [Integer] Chain ID to embed in the SIWE message (default 1).
+      #   The gateway accepts 1 or the id of any chain it has active (GET /blockchains);
+      #   anything else is refused with 422 siwe_chain_mismatch.
       # @return [Hash] { token:, address:, account_id:, name:, expires_at:, admin: }
       def login(private_key:, domain:, chain_id: 1)
         message, signature = sign_proof(private_key, domain, chain_id, LOGIN_STATEMENT)

data/lib/rail0/signing.rb

@@ -14,6 +14,7 @@ ensure
 end
 
 require_relative "tx_verify"
+require_relative "payload_verify"
 
 module Rail0
   # EIP-712 and EIP-3009 signing utilities for RAIL0 payments.
@@ -27,7 +28,7 @@ module Rail0
   # ## Typical usage (simplest path)
   #
   #   resp = client.payments.create(chain_id: 84532, mode: "authorize", amount: "100.00", token: "0x...", payer: "0x...", payee: "0x...")
-  #   sig  = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, resp[:signing_payload])
+  #   sig  = Rail0::Signing.sign_signing_payload(resp[:signing_payload], BUYER_PRIVATE_KEY, payment: resp)
   #   client.payments.sign(resp[:rail0_id], { signature: sig.to_hex })
   #
   module Signing
@@ -63,7 +64,7 @@ module Rail0
     # DEPRECATED — the parameter object of the removed {sign_authorize} /
     # {sign_charge}. Kept only so existing code reaches those methods' migration
     # message instead of a NameError while building their arguments; nothing in this
-    # SDK consumes it. Use {sign_payload} with the gateway's `signing_payload`.
+    # SDK consumes it. Use {sign_signing_payload} with the gateway's `signing_payload`.
     SignPaymentParams = Struct.new(
       :private_key, :payment, :nonce, :contract_address, :token_domain,
       keyword_init: true
@@ -279,13 +280,22 @@ module Rail0
       f = unsigned_transaction.is_a?(String) ? JSON.parse(unsigned_transaction) : unsigned_transaction
       f = f.transform_keys(&:to_s)
 
+      # Even on the deprecated blind path: Eth::Tx treats a nil or "" `to` as a
+      # contract creation and signs it, which would have this key deploy whatever init
+      # code the gateway put in `data`. No RAIL0 operation is ever a creation.
+      unless TxVerify.address?(f["to"].to_s.strip)
+        raise TxVerify::RefusedSignature,
+              "refusing to sign: the transaction's `to` #{f['to'].inspect} is not an address " \
+              "(an empty `to` would deploy a contract)"
+      end
+
       tx = Eth::Tx.new(
         chain_id:     Integer(f.fetch("chain_id")),
         nonce:        Integer(f.fetch("nonce")),
         priority_fee: Integer(f.fetch("max_priority_fee_per_gas")),
         max_gas_fee:  Integer(f.fetch("max_fee_per_gas")),
         gas_limit:    Integer(f.fetch("gas_limit")),
-        to:           f.fetch("to"),
+        to:           "0x#{f['to'].to_s.strip[2..]}",
         value:        Integer(f["value"] || 0),
         data:         f["data"].to_s
       )
@@ -299,24 +309,79 @@ module Rail0
       "0x#{tx.hex}"
     end
 
+    # Verify, then sign, the EIP-3009 +signing_payload+ of a create, get or refund
+    # prepare response. The checked form — prefer it over the bare {sign_payload}.
+    #
+    # Before the key touches the payload, {Rail0::PayloadVerify.verify} holds it to
+    # +payment:+: +message.from+ is this key's address, +domain.chainId+ the payment's
+    # chain, +domain.verifyingContract+ its token, +message.to+ its RAIL0 contract, and
+    # +message.value+ exactly the amount — +amount:+ scaled by the payment's +decimals+
+    # when given (a refund), else the payment's stored base-unit +amount+ (the payer of a
+    # created payment). A mismatch raises {Rail0::TxVerify::RefusedSignature} naming the
+    # field, and nothing is signed. Everything compared is already in hand: no extra
+    # gateway call. The payload is then signed verbatim, as {sign_payload} does.
+    #
+    #   payment = client.payments.create(chain_id: 84532, mode: "authorize", amount: "100.00", ...)
+    #   sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], BUYER_PRIVATE_KEY,
+    #                                             payment: payment)
+    #   client.payments.sign(payment[:rail0_id], { signature: sig.to_hex })
+    #
+    #   payment = client.payments.get(rail0_id)
+    #   p1  = client.payments.refund_prepare(rail0_id, amount: "50.00")
+    #   sig = Rail0::Signing.sign_signing_payload(p1[:signing_payload], MERCHANT_PRIVATE_KEY,
+    #                                             payment: payment, amount: "50.00")
+    #
+    # The key is a private-key String, an Eth::Key, or any object responding to
+    # +#sign(digest)+ AND +#address+ — the address is what +message.from+ is checked
+    # against, so a remote signer (KMS, HSM) must expose the address it signs for.
+    #
+    # @param signing_payload [Hash] the response's +signing_payload+
+    # @param private_key [String, Eth::Key, #sign] the signer
+    # @param payment [Hash] the payment record the authorization is for
+    # @param amount [String, nil] the human decimal asked for (refund); nil = the payment's amount
+    # @return [Eip3009Signature]
+    def self.sign_signing_payload(signing_payload, private_key, payment:, amount: nil)
+      signer = signer_for(private_key)
+      unless signer.respond_to?(:address)
+        raise ArgumentError,
+              "the checked signer needs the key's address to compare with the authorization's `from`: " \
+              "pass a key String or Eth::Key, or a signer responding to #address"
+      end
+
+      PayloadVerify.verify(signing_payload, payment: payment, signer: signer.address.to_s, amount: amount)
+      sign_verbatim(signer, signing_payload)
+    end
+
     # Sign the EIP-3009 payload using the signing_payload returned by POST /payments.
     #
-    # This is the simplest entry point: pass the full signing_payload from the create response
-    # and a private key — all fields are read directly from the payload without any manual
-    # reconstruction. (The payload's inner domain/message keep EIP-712 camelCase — chainId,
+    # All fields are read directly from the payload without any manual reconstruction.
+    # (The payload's inner domain/message keep EIP-712 camelCase — chainId,
     # verifyingContract, validAfter, validBefore — which this reads directly.)
     #
-    #   resp = client.payments.create(
-    #     chain_id: 84532, mode: "authorize",
-    #     amount: "100.00", token: "0x...", payer: "0x...", payee: "0x..."
-    #   )
-    #   sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, resp[:signing_payload])
-    #   client.payments.sign(resp[:rail0_id], { signature: sig.to_hex })
+    # With +payment:+ it is {sign_signing_payload}: the payload is VERIFIED against the
+    # payment first. Without it the payload is signed BLINDLY — a compromised or
+    # misconfigured endpoint could have this key sign an authorization the token honours
+    # on its own, for any amount up to the key's balance. That form is DEPRECATED (a
+    # +:deprecated+ warning is emitted; enable them with +Warning[:deprecated] = true+ or
+    # +-W:deprecated+) and will be removed in the next major version.
     #
-    # @param private_key [String] Payer's private key (0x-prefixed hex).
+    # @param private_key [String, Eth::Key, #sign] Signer (a private key, 0x-prefixed hex).
     # @param signing_payload [Hash] The signingPayload hash from the create response.
+    # @param payment [Hash, nil] The payment record the authorization is for.
+    # @param amount [String, nil] The human decimal asked for (refund).
     # @return [Eip3009Signature]
-    def self.sign_payload(private_key, signing_payload)
+    def self.sign_payload(private_key, signing_payload, payment: nil, amount: nil)
+      return sign_signing_payload(signing_payload, private_key, payment: payment, amount: amount) if payment || amount
+
+      warn("Rail0::Signing.sign_payload without payment: signs the gateway's authorization blindly " \
+           "and is deprecated; use sign_signing_payload(signing_payload, key, payment:) so it is " \
+           "verified first", uplevel: 1, category: :deprecated)
+      sign_verbatim(private_key, signing_payload)
+    end
+
+    # Signs a payload exactly as the gateway built it: domain, typehash (from its own
+    # primaryType, never guessed) and message fields all come from the payload.
+    def self.sign_verbatim(private_key, signing_payload)
       payload = symbolize(signing_payload)
       d = symbolize(payload[:domain])
       m = symbolize(payload[:message])
@@ -342,9 +407,11 @@ module Rail0
       )
     end
 
+    private_class_method :sign_verbatim
+
     # Sign a raw EIP-3009 transferWithAuthorization message.
     #
-    # For RAIL0 payment flows prefer {sign_payload} which reads all fields from the
+    # For RAIL0 payment flows prefer {sign_signing_payload} which reads all fields from the
     # API-returned signingPayload. Use this method only when you need full control over
     # the message fields (e.g. integrating with a contract directly).
     #
@@ -368,7 +435,7 @@ module Rail0
       )
     end
 
-    # REMOVED — see {sign_payload}.
+    # REMOVED — see {sign_signing_payload}.
     #
     # These two rebuilt the EIP-3009 digest from a payment record: they read
     # from/value/validBefore off the payment, hardcoded `validAfter = 0` and `to =
@@ -389,7 +456,8 @@ module Rail0
       "Rail0::Signing.%s was removed: it rebuilt the EIP-3009 digest from a payment " \
       "record, which signs the WRONG digest as soon as the contract's payload changes " \
       "(rail0#58 moves authorize/charge to ReceiveWithAuthorization). Use " \
-      "Rail0::Signing.sign_payload(private_key, create_response[:signing_payload]) — " \
+      "Rail0::Signing.sign_signing_payload(create_response[:signing_payload], private_key, " \
+      "payment: create_response) — " \
       "the gateway builds the payload, clients sign it verbatim."
     private_constant :REMOVED_MESSAGE
 

data/lib/rail0/tx_verify.rb

@@ -80,16 +80,17 @@ module Rail0
     #    transfers the contract performs, so a non-zero value is the gateway asking for ETH;
     # 3. +chain_id+ is the payment's chain;
     # 4. +from+, when present, is +signer+ (the signing key's address);
-    # 5. +to+ is the payment's +rail0_contract+ — a consistency check (the address comes
-    #    from the same gateway), but it catches a response stitched from two payments;
+    # 5. +to+ is an address and is the payment's +rail0_contract+ — a consistency check
+    #    (the address comes from the same gateway), but it catches a response stitched
+    #    from two payments, and an empty +to+ (a contract creation) always refuses;
     # 6. the 4-byte selector is the RAIL0 function for +operation+, and for capture and
     #    refund the amount word equals +amount+ scaled by the payment's +decimals+;
     # 7. the paymentId word is the payment's +rail0_id+.
     #
     # Every right-hand side is something the caller supplied or derived locally — never
     # the prepare response itself. FAIL-CLOSED on what cannot be compared: an unknown
-    # operation, a capture/refund without an +amount+, or a payment with unknown
-    # +decimals+ refuses rather than skips. Only the paymentId comparison is skipped,
+    # operation, a capture/refund without an +amount+, a payment with no
+    # +rail0_contract+ or with unknown +decimals+ refuses rather than skips. Only the paymentId comparison is skipped,
     # when the payment carries no usable +rail0_id+.
     #
     # @param unsigned_transaction [String, Hash] the prepare response's field-set
@@ -126,10 +127,34 @@ module Rail0
         refuse("transaction is prepared from #{from} but the signing key is #{signer}")
       end
 
-      to = fields["to"].to_s
-      return unless pay[:rail0_contract] && !to.empty? && !same_address?(to, pay[:rail0_contract])
+      check_to(fields["to"], pay[:rail0_contract])
+    end
+
+    # Check 5. +to+ used to be compared only when it was present: an absent, nil or ""
+    # +to+ skipped the check, and Eth::Tx signs a transaction with no recipient as a
+    # CONTRACT CREATION — the calldata becomes init code run by the signing key, which
+    # deploys whatever the gateway sent from the merchant's own account. So an empty or
+    # malformed +to+ refuses outright, and so does a payment record with no
+    # +rail0_contract+ to compare it with: every RAIL0 operation is a call to that one
+    # contract, and nothing else here can tell a legitimate recipient from a hostile one.
+    def self.check_to(to_field, rail0_contract)
+      to = to_field.to_s.strip
+      refuse("the transaction has no `to` address; signing it would deploy a contract") if to.empty?
+      refuse("the transaction's `to` #{to.inspect} is not an address") unless address?(to)
+      if rail0_contract.nil?
+        refuse("cannot check the transaction's `to` without the payment's rail0_contract " \
+               "(fetch the payment with payments.get first)")
+      end
+      return if same_address?(to, rail0_contract)
 
-      refuse("transaction is addressed to #{to} but this payment's RAIL0 contract is #{pay[:rail0_contract]}")
+      refuse("transaction is addressed to #{to} but this payment's RAIL0 contract is #{rail0_contract}")
+    end
+
+    # A 20-byte, 0x-prefixed hex address, any case (prefix included). Shared with
+    # {Rail0::PayloadVerify} and the signer, which applies it even to the deprecated
+    # blind form.
+    def self.address?(value)
+      value.is_a?(String) && value.match?(/\A0x\h{40}\z/i)
     end
 
     def self.parse(unsigned_transaction)
@@ -152,7 +177,7 @@ module Rail0
       s.empty? ? nil : s
     end
 
-    private_class_method :check_header, :parse, :payment_fields, :presence
+    private_class_method :check_header, :check_to, :parse, :payment_fields, :presence
 
     def self.refuse(message)
       raise RefusedSignature, "refusing to sign: #{message}"
@@ -197,6 +222,12 @@ module Rail0
     # String math, no Float: "1.5" at 6 decimals is "1500000". More fractional digits
     # than the token has is a refusal, not a truncation — the gateway 422s such an
     # amount, so dropping digits would compare against a figure never asked for.
+    # Public because {Rail0::PayloadVerify} scales the caller's amount the same way.
+    #
+    # @param human [String] a decimal amount as the caller typed it ("1.5")
+    # @param decimals [Integer] the token's decimals
+    # @return [String] the amount in base units
+    # @raise [RefusedSignature] when it is not a plain decimal, or is finer than +decimals+
     def self.to_base_units(human, decimals)
       s = human.strip
       refuse("amount #{human.inspect} is not a decimal number") unless s.match?(/\A\d+(\.\d+)?\z/)
@@ -208,7 +239,7 @@ module Rail0
       (whole + frac.ljust(decimals, "0")).sub(/\A0+(?=\d)/, "")
     end
 
-    private_class_method :expected_base_units, :to_base_units
+    private_class_method :expected_base_units
 
     # Asserts the call is the RAIL0 function for +operation+ and, for capture and refund,
     # that it moves exactly +want_units+ base units.

data/lib/rail0/types.rb

@@ -457,17 +457,17 @@ module Rail0
       keyword_init: true
     )
 
-    # One reported policy value.
-    PolicySetting = Struct.new(
+    # One reported configuration value.
+    ConfigSetting = Struct.new(
       :value,        # The effective value (number, boolean, string, list or map).
       :env,          # String — The environment variable that sets it; null for a constant.
       :overridden,   # Boolean — Whether that variable is set in this process.
-      :description,  # String — Plain-text explanation of the entry: what it controls, which part of the gateway reads it and the effect of raising or lowering it, and its unit (from config/policy_descriptions.yml). Every entry has one; older gateways omit the field.
+      :description,  # String — Plain-text explanation of the entry: what it controls, which part of the gateway reads it and the effect of raising or lowering it, and its unit (from config/config_descriptions.yml). Every entry has one; older gateways omit the field.
       keyword_init: true
     )
 
-    # GET /admin/policy: the effective policy, grouped. Every leaf is a PolicySetting.
-    PolicyReport = Struct.new(
+    # GET /admin/config: the effective configuration, grouped. Every leaf is a ConfigSetting.
+    ConfigReport = Struct.new(
       :payments,      # Hash
       :recovery,      # Hash
       :retention,     # Hash

data/lib/rail0/version.rb

@@ -5,5 +5,5 @@ module Rail0
   # consumed by path from a sibling checkout, where the number bought nothing: no registry
   # ever served a 1.x, no tag was ever cut, and the one consumer resolves the working tree.
   # Publishing from 1.2.0 would have implied two releases nobody can install.
-  VERSION = "1.6.0"
+  VERSION = "1.7.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.1
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -44,6 +44,7 @@ files:
 - lib/rail0/dispute_reasons.rb
 - lib/rail0/error_hints.rb
 - lib/rail0/http_client.rb
+- lib/rail0/payload_verify.rb
 - lib/rail0/request.rb
 - lib/rail0/resources/accounts.rb
 - lib/rail0/resources/analytics.rb