rail0-sdk 1.7.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 861d8ebab53accbd5a962ed1cb040a91461841b63722077b93374291f8de66bd
-  data.tar.gz: e7d22a5a5d2e9ad6a22149427195b1d7d341e15da84e1d858f453d343859b771
+  metadata.gz: 5d88d3da009d4c04853e8fb794eba655913763a1391c6e0bd6915bda6cb68d36
+  data.tar.gz: 5cc37022ce71f950c6b11dcf421902518b63caebfd54a13f78eaf909a7eef39c
 SHA512:
-  metadata.gz: b926413fd2b987d43b60b78216506baa56eb8954c3d51c7ba2e61a977e597a250c2b961772a27fba93bca1a2f08b036250c15111ecac692823e3ab84548f2004
-  data.tar.gz: a43b612c63ea9114034c4e80eeccb9670758bfecae1267efe5568f322475adfc8dcdf2f935b35f40d9cfcf8559b94b1e65a00b36093c937bf5ac6a385920ba5c
+  metadata.gz: 2512e0a842d7d76749dc4028a0c1d2590b7fe1dd4e95676572a39aa8c41fa9a882c2e4a534e85080f0fe8089c8001c6f2101ff4b9fb7ab9f4e2cc9d7e6d35d62
+  data.tar.gz: 7b569639525815722a586f308d45ebc67c964cbd4f6f1ae4c5bac4a8c5a731589b03dffebcfcdb375e3a265f9f1143b52162d5e8685de591e39a364de3257cf8

data/README.md

@@ -150,8 +150,16 @@ signs after `create` (and the payee signs in refund phase 1) is the more dangero
 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, against data you already hold:
-`message.from` is your key's address, `domain.chainId` the payment's `chain_id`,
+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
@@ -827,7 +835,7 @@ Requires the `eth` gem. No private key ever leaves your process.
 |--------|-----|
 | `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 |
+| `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 |
@@ -846,7 +854,8 @@ client.payments.sign(payment[:rail0_id], { signature: sig.to_hex })
 **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.
 

data/lib/rail0/payload_verify.rb

@@ -27,10 +27,17 @@ module Rail0
   # 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 +primaryType+
-  # against the contract version (the signer already refuses an unknown one), the
+  # 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
@@ -62,6 +69,7 @@ module Rail0
       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|
@@ -91,6 +99,73 @@ module Rail0
 
     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)

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.7.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.7.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