bsv-sdk 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6ca8a4c5f04ec956d46b46d18286a7dad889496c1ae2683ff79210c01e10529
-  data.tar.gz: d2c327e4b61a979909dd31f4755f852c3d0c6153f00c135c446ec64386f5709a
+  metadata.gz: 534417702a1c6fe35494ff3d7bc028d302452fc21312747cd83167137fab43c7
+  data.tar.gz: d7aca5b47d7f853f41142d2ae9087351bf0160beb0b25959330e7e380bbb5d92
 SHA512:
-  metadata.gz: 015f6727214704a6a972f1fd6f8cc7c9597f21df21ab794698d9862f7c9a4df702f33be01cec402dc5726240137ae22137f74e08cfc820dd25204ffa92b32768
-  data.tar.gz: 53517f95c64d850fa7b164f4b785020d81866525d9bda7623e22eeb89ba7a55d61f9d8c17abadf8cadcee9a5a4469516bbe9f87102f50bbc2f32559963ff5fd0
+  metadata.gz: 109f3d7d92f210bb3bc5df4e2defaec5322be06b33a467023109fef27d1c9ffe8ca2f876b865b9a4e9f21ef69e9f5d19dd8fde5b02cefdd58f3ee2ac58cfae41
+  data.tar.gz: 70145605156016e9fbcd6a4c397a317358ad3142c97637d6ad8a849934ac8d356f40c555e55af178280693c3c4d6b1d3f76af8f10df5526e6fde6fefdef928c5

data/CHANGELOG.md

@@ -21,6 +21,124 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and each gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 independently.
 
+## sdk-0.8.2 / wallet-0.3.4 — 2026-04-08
+
+Paired security patch release. Three P0 findings from the
+[2026-04-08 cross-SDK compliance review](.architecture/reviews/20260408-cross-sdk-compliance-review.md)
+plus follow-up hardening from the PR review pass. Must be installed
+together — the `bsv-wallet` gemspec now pins its `bsv-sdk` dependency
+to `>= 0.8.2, < 1.0` to enforce the paired upgrade and prevent a stale
+pair where one gem has its fixes and the other doesn't.
+
+Two GitHub Security Advisories accompany this release (draft until
+CVE IDs return from MITRE):
+
+- [GHSA-hc36-c89j-5f4j](.security/advisories/2026-0001-acquire-certificate-signature-bypass.md) — F8.15 / F8.16 partial — `acquire_certificate` persists unverified certifier signatures (CWE-347, CVSS 8.1 HIGH)
+- [GHSA-9hfr-gw99-8rhx](.security/advisories/2026-0002-arc-broadcaster-failure-statuses.md) — F5.13 — ARC broadcaster treats failure statuses as success (CWE-754, CVSS 7.5 HIGH)
+
+### Security
+
+- [wallet] **`acquire_certificate` now verifies certifier signatures** before
+  persisting (BRC-52). Both the `'direct'` and `'issuance'` acquisition
+  paths previously wrote user-supplied `signature:` values to storage
+  without any verification — a caller could forge a certificate that
+  `list_certificates` / `prove_certificate` would later treat as
+  authentic. This was a credential forgery primitive masquerading as
+  an API finding. The new `BSV::Wallet::CertificateSignature` module
+  builds the canonical BRC-52 preimage (matching the TS reference
+  `Certificate#toBinary(false)` byte-for-byte) and delegates to
+  `ProtoWallet#verify_signature`. Invalid certificates raise
+  `BSV::Wallet::CertificateSignature::InvalidError` and are not
+  persisted. Closes F8.15 (and the verification aspect of F8.16).
+
+- [sdk] **`VarInt.encode` now rejects negative integers** and values
+  above 2^64 − 1. Previously `VarInt.encode(-1)` fell into the single-
+  byte branch and emitted `0xFF` (the marker for a 9-byte encoding),
+  silently corrupting the transaction stream with no exception raised.
+  The docstring already required a non-negative integer; the
+  implementation did not enforce it. Closes F1.3.
+
+- [sdk] **ARC broadcaster recognises the full failure status set**. The
+  previous `REJECTED_STATUSES` contained only `REJECTED` and
+  `DOUBLE_SPEND_ATTEMPTED`; responses with txStatus `INVALID`,
+  `MALFORMED`, `MINED_IN_STALE_BLOCK`, or any `ORPHAN`-containing
+  `txStatus` / `extraInfo` were silently treated as successful
+  broadcasts. Callers relying on `broadcast()` to signal failure would
+  trust transactions that were never actually accepted by the network.
+  The new failure set matches the TypeScript reference broadcaster
+  exactly, and case-insensitive matching defends against ARC's
+  documented history of emitting values outside its own OpenAPI enum
+  (TS issue #105). Malformed 2xx responses without a `txid` field
+  also raise, closing the same silent-success class for shape
+  corruption. Closes F5.13.
+
+### Changed
+
+- [sdk] **ARC broadcaster HTTP wire format** brought into line with the
+  TypeScript reference:
+  - Content-Type is now `application/json` (was `application/octet-stream`)
+  - Body is `{"rawTx": hex}` — Extended Format (BRC-30) hex when every
+    input has `source_satoshis` / `source_locking_script` populated
+    (so ARC can validate sighashes without fetching parents), falling
+    back to plain raw-tx hex otherwise
+  - New `XDeployment-ID` header (default: `bsv-ruby-sdk-<random hex>`,
+    overridable via `deployment_id:` constructor kwarg)
+  - New optional `X-CallbackUrl` and `X-CallbackToken` constructor
+    kwargs for ARC status callbacks
+
+- [wallet] **`bsv-wallet.gemspec` bsv-sdk dependency pinned** to
+  `>= 0.8.2, < 1.0`. The previous `~> 0.4` constraint was stale (wallet
+  hasn't been tested against bsv-sdk 0.4.x in months) and would have
+  let a user install `bsv-wallet 0.3.4` against an old `bsv-sdk` that
+  was missing F1.3 and F5.13. Technically breaking — any consumer
+  pinned to `bsv-sdk < 0.8.2` must upgrade — but un-breaking in
+  practice: it forces users to the known-good pair rather than a
+  silently-broken combination.
+
+### Internal
+
+- [sdk] `lib/bsv/network/**/*` added to `Metrics/ClassLength` and
+  `Metrics/ParameterLists` RuboCop exclusion lists to match the
+  existing treatment of `lib/bsv/wallet_interface/**/*`. ARC is
+  HTTP-client boilerplate in the same shape.
+- [wallet] `lib/bsv/wallet_interface/**/*` added to the
+  `Metrics/ModuleLength` exclusion list (was previously only excluded
+  from `Metrics/ClassLength`). The new `CertificateSignature` module
+  triggered the discrepancy.
+- [sdk, wallet] Review-feedback hardening bundled into the same PR to
+  keep the security-patch window small: case-insensitive ARC failure
+  matching, `Base64.strict_decode64` on BRC-52 preimage fields,
+  `EncodingError` rescue in `CertificateSignature.verify!`, rejection
+  of mixed string / symbol duplicate field names, malformed 2xx
+  rejection in ARC, and even-length guard on hex signatures.
+
+### Migration notes
+
+- **Existing `bsv-wallet` users** pinned to `bsv-sdk ~> 0.4` will need
+  to relax their constraint or upgrade. Anything installed before
+  `bsv-wallet 0.3.4` is vulnerable to the F8.15 certificate forgery
+  primitive.
+- **Callers passing negative integers to `VarInt.encode`** (unlikely —
+  the docstring already disallowed it) will now get an `ArgumentError`
+  instead of silent corruption. Fix: pass non-negative values.
+- **Callers relying on ARC broadcaster silently succeeding for INVALID
+  / MALFORMED / MINED_IN_STALE_BLOCK / ORPHAN responses** will now see
+  `BroadcastError` raised. Fix: handle the error — the previous
+  behaviour was objectively wrong and any downstream logic that
+  tolerated it was silently corrupt.
+- **Callers of `acquire_certificate` with a fake or untrusted
+  `signature:` field** will now see
+  `BSV::Wallet::CertificateSignature::InvalidError`. Fix: ensure the
+  certificate has been properly signed by the declared certifier.
+
+### Test suite
+
+- 3112 examples, 0 failures (up from 3080 on 0.8.1)
+- 16 new regression tests for F1.3, F5.13, and F8.15
+- 16 further regression tests for the review-feedback hardening
+- Ruby 2.7 — 3.4 matrix green
+- CodeQL clean; RuboCop clean across 266 files
+
 ## sdk-0.8.1 — 2026-04-08
 
 ### Fixed

data/lib/bsv/network/arc.rb

@@ -3,6 +3,7 @@
 require 'net/http'
 require 'json'
 require 'uri'
+require 'securerandom'
 
 module BSV
   module Network
@@ -14,16 +15,48 @@ module BSV
     # The HTTP client is injectable for testability. It must respond to
     # #request(uri, request) and return an object with #code and #body.
     class ARC
-      REJECTED_STATUSES = %w[REJECTED DOUBLE_SPEND_ATTEMPTED].freeze
-
-      def initialize(url, api_key: nil, http_client: nil)
+      # ARC response statuses that indicate the transaction was NOT accepted.
+      # Matches the TypeScript SDK's ARC broadcaster failure set (issue #305,
+      # finding F5.13). Prior to this fix, Ruby only recognised REJECTED and
+      # DOUBLE_SPEND_ATTEMPTED, silently treating INVALID / MALFORMED /
+      # MINED_IN_STALE_BLOCK responses as successful broadcasts.
+      REJECTED_STATUSES = %w[
+        REJECTED
+        DOUBLE_SPEND_ATTEMPTED
+        INVALID
+        MALFORMED
+        MINED_IN_STALE_BLOCK
+      ].freeze
+
+      # Substring match for orphan detection in txStatus or extraInfo fields.
+      ORPHAN_MARKER = 'ORPHAN'
+
+      # @param url [String] ARC base URL (without trailing slash)
+      # @param api_key [String, nil] optional bearer token for Authorization
+      # @param deployment_id [String, nil] optional deployment identifier for
+      #   the +XDeployment-ID+ header; defaults to a per-instance random value
+      # @param callback_url [String, nil] optional +X-CallbackUrl+ for ARC
+      #   status callbacks
+      # @param callback_token [String, nil] optional +X-CallbackToken+ for
+      #   ARC status callback authentication
+      # @param http_client [#request, nil] injectable HTTP client for testing
+      def initialize(url, api_key: nil, deployment_id: nil, callback_url: nil,
+                     callback_token: nil, http_client: nil)
         @url = url.chomp('/')
         @api_key = api_key
+        @deployment_id = deployment_id || "bsv-ruby-sdk-#{SecureRandom.hex(8)}"
+        @callback_url = callback_url
+        @callback_token = callback_token
         @http_client = http_client
       end
 
       # Submit a transaction to ARC.
       #
+      # The transaction is encoded as Extended Format (BRC-30) hex when every
+      # input has +source_satoshis+ and +source_locking_script+ populated,
+      # which lets ARC validate sighashes without fetching parents. Falls back
+      # to plain raw-tx hex when EF is unavailable.
+      #
       # @param tx [Transaction] the transaction to broadcast
       # @param wait_for [String, nil] ARC wait condition — one of
       #   'RECEIVED', 'STORED', 'ANNOUNCED_TO_NETWORK',
@@ -31,14 +64,18 @@ module BSV
       #   connection open until the transaction reaches the requested
       #   state (or times out). Defaults to nil (no wait).
       # @return [BroadcastResponse]
-      # @raise [BroadcastError]
+      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
+      #   rejected/orphan +txStatus+
       def broadcast(tx, wait_for: nil)
         uri = URI("#{@url}/v1/tx")
         request = Net::HTTP::Post.new(uri)
-        request['Content-Type'] = 'application/octet-stream'
+        request['Content-Type'] = 'application/json'
+        request['XDeployment-ID'] = @deployment_id
         request['X-WaitFor'] = wait_for if wait_for
+        request['X-CallbackUrl'] = @callback_url if @callback_url
+        request['X-CallbackToken'] = @callback_token if @callback_token
         apply_auth_header(request)
-        request.body = tx.to_binary
+        request.body = JSON.generate(rawTx: raw_tx_hex(tx))
 
         response = execute(uri, request)
         handle_broadcast_response(response)
@@ -49,6 +86,7 @@ module BSV
       def status(txid)
         uri = URI("#{@url}/v1/tx/#{txid}")
         request = Net::HTTP::Get.new(uri)
+        request['XDeployment-ID'] = @deployment_id
         apply_auth_header(request)
 
         response = execute(uri, request)
@@ -57,6 +95,15 @@ module BSV
 
       private
 
+      # Prefer Extended Format (BRC-30) hex so ARC can validate sighashes
+      # without fetching parent transactions. Falls back to plain raw-tx hex
+      # when any input lacks source_satoshis / source_locking_script.
+      def raw_tx_hex(tx)
+        tx.to_ef_hex
+      rescue ArgumentError
+        tx.to_hex
+      end
+
       def apply_auth_header(request)
         request['Authorization'] = "Bearer #{@api_key}" if @api_key
       end
@@ -83,20 +130,45 @@ module BSV
           )
         end
 
-        tx_status = body['txStatus']
-        if rejected_status?(tx_status)
+        if rejected_status?(body)
           raise BroadcastError.new(
-            body['detail'] || body['title'] || tx_status,
+            body['detail'] || body['title'] || body['txStatus'],
             status_code: code,
             txid: body['txid']
           )
         end
 
+        # A 2xx response without a txid is a malformed ARC reply —
+        # `parse_json` falls back to `{'detail' => raw}` on non-JSON,
+        # which would otherwise produce a `BroadcastResponse` full of
+        # `nil`s and `success? => true`. That's the same silent
+        # success-as-failure class of bug F5.13 closed for explicit
+        # error statuses; closing it here for shape corruption too.
+        unless body['txid']
+          raise BroadcastError.new(
+            'ARC returned a malformed 2xx response',
+            status_code: code
+          )
+        end
+
         build_response(body)
       end
 
-      def rejected_status?(tx_status)
-        REJECTED_STATUSES.include?(tx_status)
+      def rejected_status?(body)
+        # Case-insensitive match — the TypeScript reference
+        # (`ts-sdk/src/transaction/broadcasters/ARC.ts:155-166`) explicitly
+        # `.toUpperCase()`s both fields before membership / substring checks.
+        # ARC has a documented history of emitting values outside its own
+        # OpenAPI enum (e.g. `txStatus: "success"` for orphans in TS issue
+        # #105), so case normalisation is the defensive choice.
+        tx_status = body['txStatus'].to_s.upcase
+        return true if REJECTED_STATUSES.include?(tx_status)
+        return true if tx_status.include?(ORPHAN_MARKER)
+
+        extra_info = body['extraInfo'].to_s.upcase
+        return true if extra_info.include?(ORPHAN_MARKER)
+
+        false
       end
 
       def parse_json(raw)

data/lib/bsv/transaction/var_int.rb

@@ -10,11 +10,18 @@ module BSV
     module VarInt
       module_function
 
+      # Maximum value representable by a Bitcoin VarInt (unsigned 64-bit).
+      MAX_UINT64 = 0xFFFF_FFFF_FFFF_FFFF
+
       # Encode an integer as a Bitcoin VarInt.
       #
-      # @param value [Integer] non-negative integer to encode
+      # @param value [Integer] non-negative integer to encode (0..2^64-1)
       # @return [String] encoded binary bytes
+      # @raise [ArgumentError] if +value+ is negative or exceeds 2^64-1
       def encode(value)
+        raise ArgumentError, "varint requires non-negative integer, got #{value}" if value.negative?
+        raise ArgumentError, "varint value #{value} exceeds uint64 max (#{MAX_UINT64})" if value > MAX_UINT64
+
         if value < 0xFD
           [value].pack('C')
         elsif value <= 0xFFFF

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.8.1'
+  VERSION = '0.8.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Simon Bettison