rail0-sdk 1.7.0 → 1.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 861d8ebab53accbd5a962ed1cb040a91461841b63722077b93374291f8de66bd
-  data.tar.gz: e7d22a5a5d2e9ad6a22149427195b1d7d341e15da84e1d858f453d343859b771
+  metadata.gz: 3c69ef678235fc14acf0f3bcaebc302bd3b63d6dd1b41a1358381b49fd6a9738
+  data.tar.gz: 1d42362b54cf2118b2150087211bd7f5df49a8248278af49603fd745d32be08b
 SHA512:
-  metadata.gz: b926413fd2b987d43b60b78216506baa56eb8954c3d51c7ba2e61a977e597a250c2b961772a27fba93bca1a2f08b036250c15111ecac692823e3ab84548f2004
-  data.tar.gz: a43b612c63ea9114034c4e80eeccb9670758bfecae1267efe5568f322475adfc8dcdf2f935b35f40d9cfcf8559b94b1e65a00b36093c937bf5ac6a385920ba5c
+  metadata.gz: 061516a40ea00e3ebf114f9ae841bfac830682f443caaa8f82fbe4789de91d1eab760896c6a0447a371092cd01f5bbb9f30200e8e17f0897bce60390ba541e82
+  data.tar.gz: 5f0e8c80653d3234d24f2816f607a84ecfb99c743afa2dd58fa64d3c184510458796ab54efc8cad00c7b478f35a26bf68d6339e1c592dff8d2712d087e3aae03

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
@@ -374,6 +382,7 @@ client.wallets.list(account_id, token_active: true)
 
 client.wallets.get(account_id, id_or_address)
 client.wallets.update(account_id, id_or_address, label: "Renamed", active: false)
+client.wallets.update(account_id, id_or_address, active: true)      # back on (see below)
 client.wallets.delete(account_id, id_or_address)                    # 204
 client.wallets.balances(account_id, id_or_address, chain_id: 84532) # live on-chain balances
 ```
@@ -384,6 +393,17 @@ refused with 422 `last_active_wallet` — login resolves the account from a wall
 so an account with none could neither act nor add one back. Another wallet must
 be active first.
 
+**Switching a wallet back on.** Every switch-off records who did it in the wallet's
+`deactivated_by`: `"owner"` (a session signed in with that wallet) or `"operator"`
+(an operator session); `nil` while active, and on a switch-off older than the record.
+A deactivated wallet's session is read-only (403 `wallet_deactivated`) except for one
+write: `update(account_id, id, active: true)` on its **own** wallet, which switches it
+back on when its owner switched it off. A wallet an operator switched off (or with
+`deactivated_by: nil`) raises 403 `wallet_deactivated_by_operator`: an operator's
+switch-off revokes the key, so only an operator lifts it. The flip side: a wallet its
+owner switched off can be switched back on by whoever holds its key, so a definitive
+revocation (a leaked key) must come from an operator.
+
 **A session is bound to the wallet it signed in with.** Reads (`list`, `get`,
 `balances`) are account-wide, but `update`, `delete` and the token-holding methods
 act only on the session's own wallet: another wallet of the same account is
@@ -827,7 +847,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 +866,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/error_hints.rb

@@ -55,7 +55,10 @@ module Rail0
     "not_payer_or_payee" => "only the payer or the payee may do this",
     "release_submitter_not_a_party" => "a release must be sent by the payment's payer or payee — omit `from` to build it for the signed-in wallet",
     "payer_must_be_caller" => "the payer must be the signed-in wallet — sign in as the buyer to create its payment",
-    "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — reactivate it or sign in with another of the account's wallets",
+    # gateway#439: a deactivated session may switch its OWN wallet back on when its owner
+    # switched it off; an operator's switch-off is the operator's to lift.
+    "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — if you switched it off, its own session can switch it back on (wallets.update(..., active: true)), or sign in with another of the account's wallets",
+    "wallet_deactivated_by_operator" => "an operator deactivated this wallet, so only an operator can reactivate it — ask an operator to reactivate it",
     "account_deactivated" => "the merchant account is deactivated: void, release and refund still work, but authorize, charge, capture and account changes do not — ask an operator to reactivate it",
     # A session is bound to the one wallet it signed in with: the account's other wallets
     # are readable, but not this session's to change (operators are exempt).
@@ -65,8 +68,9 @@ module Rail0
     "wallet_add_unavailable" => "adding a wallet to an account is not available yet — it returns with the merchant wallet-management section",
     # Login resolves the account FROM a wallet, so an account left with no active one
     # could neither act nor add a wallet back. Adding a wallet is suspended and a session
-    # changes only its own wallet, so the other wallet has to be reactivated by an operator.
-    "last_active_wallet" => "this is the account's only active wallet — another wallet must be active before this one can be switched off (adding a wallet is not available yet; an operator can reactivate one)",
+    # changes only its own wallet, so the other wallet comes back on from its own session
+    # (if its owner switched it off) or from an operator (gateway#439).
+    "last_active_wallet" => "this is the account's only active wallet — another wallet must be active before this one can be switched off: sign in with one you switched off and reactivate it, or ask an operator (adding a wallet is not available yet)",
     "last_admin" => "the change would leave no active operator — grant the operator role to another active account first",
     "not_redrivable" => "only a pending transaction that already holds its signed bytes can be redriven — check the transaction's `redrivable` flag, and submit the signature if it has none",
     "refund_expired" => "the refund window has closed (refundExpiry passed) — refund/dispute is no longer possible",

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/resources/wallets.rb

@@ -92,11 +92,16 @@ module Rail0
       # operator may change any). +active: false+ on the account's only active wallet
       # raises ApiError 422 +last_active_wallet+: login resolves the account from a
       # wallet, so an account with none could neither act nor add one back.
+      #
+      # +active: true+ is the one write a deactivated wallet's own session may make: it
+      # switches the wallet back on when its owner switched it off. A wallet an operator
+      # switched off (+deactivated_by+ "operator", or nil on an older switch-off) raises
+      # ApiError 403 +wallet_deactivated_by_operator+: only an operator lifts it.
       # @param account_id [String] Account UUID.
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @param label [String, nil] New label.
       # @param active [Boolean, nil] New active status.
-      # @return [Hash] id, address, label, active
+      # @return [Hash] id, address, label, active, deactivated_by
       def update(account_id, id_or_address, label: nil, active: nil)
         body = {}
         body[:label]  = label  unless label.nil?

data/lib/rail0/types.rb

@@ -209,10 +209,11 @@ module Rail0
 
     # Public-safe wallet view (the reduced set a buyer needs to discover a merchant's payment methods).
     Wallet = Struct.new(
-      :id,       # String
-      :address,  # String
+      :id,              # String
+      :address,         # String
       :label,
-      :active,   # Boolean
+      :active,          # Boolean
+      :deactivated_by,  # Who switched the wallet off: `owner` (a session signed in with this wallet) or `operator` (an admin session). Null while active, and on a switch-off that predates the record — treated as `operator`. A wallet an operator switched off can be switched back on only by an operator (403 `wallet_deactivated_by_operator`). Always null on GET /payment_methods, which serves active wallets only.
       keyword_init: true
     )
 
@@ -229,11 +230,12 @@ module Rail0
     # A wallet with its token holdings nested inline. `tokens` is empty when the wallet has none — the
     # wallet is still returned, never omitted.
     WalletWithTokens = Struct.new(
-      :id,       # String
-      :address,  # String
+      :id,              # String
+      :address,         # String
       :label,
-      :active,   # Boolean
-      :tokens,   # Array
+      :active,          # Boolean
+      :deactivated_by,  # Who switched the wallet off: `owner` (a session signed in with this wallet) or `operator` (an admin session). Null while active, and on a switch-off that predates the record — treated as `operator`. A wallet an operator switched off can be switched back on only by an operator (403 `wallet_deactivated_by_operator`). Always null on GET /payment_methods, which serves active wallets only.
+      :tokens,          # Array
       keyword_init: true
     )
 
@@ -457,24 +459,25 @@ 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
       :webhooks,      # Hash
       :settlement,    # Hash
       :rate_limit,    # Hash
-      :siwe,          # Hash
+      :siwe,          # Hash — domains (SIWE_DOMAIN), accepted_chain_ids (1 plus the ids of the active catalog chains: the chainId values a login may carry) and nonce_ttl.
+      :session,       # Hash — environment (RAIL0_ENVIRONMENT, default RACK_ENV: the scope every issued token is bound to), jwt_ttl and jwt_audience: the session token's lifetime (a constant) and audience (`rail0-gateway:<environment>`).
       :fees,          # Hash
       :rpc,           # Hash
       :onboarding,    # Hash
@@ -532,18 +535,5 @@ module Rail0
       :contract_address,  # String — Address (lowercase) of the RAIL0 deployment the payment is bound to, archived versions included. The sweeper accepts a receipt's event only when this contract emitted it.
       keyword_init: true
     )
-
-    # Per-chain indexer config.
-    SyncBlockchain = Struct.new(
-      :chain_id,                # Integer
-      :start_block,             # Integer
-      :required_confirmations,  # Integer — Fallback burial depth, used where the chain serves no finality tag.
-      :finality_tag,            # String — Which block the chain calls settled; the indexer gates every notify on it.
-      :explorer_url,            # Block explorer base URL; null when the chain has none.
-      :network_type,            # String — "testnet" or "mainnet"; selects which chains a deployment indexes.
-      :rpc_urls,                # Array — Ordered list of public RPC endpoints tried in turn (serial fallback).
-      :contracts,               # Array — Active RAIL0 contract addresses on the chain (all watched versions).
-      keyword_init: true
-    )
   end
 end

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.2"
 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.2
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger