bsv-wallet 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 805b24a04420fa0daee7a9fc68ee08aff7d940c31268a2317b3f00bc9e254e8d
-  data.tar.gz: fe999637c2e283f9b8e73b2bc85bf9c28ae58ebca0651168d8d44e91fe3e5f2f
+  metadata.gz: 1f3c7d9f919b64229f0c2c9c99a05fbd58850803af74861157f884ade90f7af6
+  data.tar.gz: c655fbf296f6a4a3ed554681b8ab673c8dd3d108d37e6832cbf48814b3ed2169
 SHA512:
-  metadata.gz: f49ae42829e1895a44bf0f414a6367bea7ed27295355f563d785e16ebc2a351f172ea9390549eae0e2e9497ef9c40cdaecd4ae56ec82c15fccbf681edc1d3019
-  data.tar.gz: 2d74586aa8cfc467d56da95834cf03830b90a1f7e7990ed462c7d8529f7c2e0f54f47b0061a05cddf3fa6e0c719ee1abbb01dad45394848c0b6229b33e4237c4
+  metadata.gz: 87e2b8653d787445a281fb78393e380857799852908487cbef82af26a3e1e04f16df5f67ce295ed4162742527d7ebc5d1380b4670f8a949b78d4c44524e6ab66
+  data.tar.gz: 9d288d1787f7448278eb95de1e96e41384e0c06141c755812549b9bc693c0269b8361cf31982f6b38472be3418ef575e7f373bde11d3ef0892743041c14dab10

data/lib/bsv/wallet_interface/certificate_signature.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Wallet
+    # BRC-52 identity certificate signature verification.
+    #
+    # Certificates carry a signature from the certifier over a canonical
+    # binary serialisation of their fields (excluding the signature itself).
+    # This module builds that canonical serialisation and delegates
+    # verification to a {ProtoWallet}-compatible verifier.
+    #
+    # Every field is included in the preimage in this order:
+    #
+    # - +type+ (base64 → 32 bytes)
+    # - +serial_number+ (base64 → 32 bytes)
+    # - +subject+ (hex → 33-byte compressed pubkey)
+    # - +certifier+ (hex → 33-byte compressed pubkey)
+    # - +revocation_outpoint+: txid hex (32 bytes) + output index VarInt
+    # - +fields+: VarInt count, then for each field (sorted
+    #   lexicographically by name): VarInt name length + UTF-8 name bytes
+    #   + VarInt value length + UTF-8 value bytes
+    #
+    # Signing uses BRC-42 key derivation with:
+    #
+    # - protocol ID: +[2, 'certificate signature']+
+    # - key ID: +"\#{type} \#{serial_number}"+
+    # - counterparty on sign: +'anyone'+ (default of
+    #   +ProtoWallet#create_signature+ in TS — Ruby consumers should pass
+    #   it explicitly since Ruby defaults to +'self'+)
+    # - counterparty on verify: the certifier's public key hex
+    #
+    # @see https://hub.bsvblockchain.org/brc/wallet/0052 BRC-52
+    module CertificateSignature
+      PROTOCOL_ID = [2, 'certificate signature'].freeze
+
+      # Error raised when a certificate's signature cannot be verified.
+      class InvalidError < InvalidSignatureError
+        def initialize(detail)
+          super("certificate signature verification failed: #{detail}")
+        end
+      end
+
+      module_function
+
+      # Verify a certificate's certifier signature.
+      #
+      # Raises {InvalidError} if the signature is missing, malformed, or
+      # does not match the expected certifier.
+      #
+      # @param cert [Hash] certificate fields. Required keys:
+      #   +:type+, +:serial_number+, +:subject+, +:certifier+,
+      #   +:revocation_outpoint+, +:fields+, +:signature+
+      # @param verifier [#verify_signature] optional verifier; defaults to
+      #   a fresh +ProtoWallet.new('anyone')+
+      # @return [true] when the signature verifies
+      # @raise [InvalidError] otherwise
+      def verify!(cert, verifier: ProtoWallet.new('anyone'))
+        signature_hex = cert[:signature]
+        raise InvalidError, 'signature is missing' if signature_hex.nil? || signature_hex.empty?
+
+        preimage = serialise_preimage(cert)
+        sig_bytes = hex_to_bytes(signature_hex)
+
+        verifier.verify_signature({
+                                    data: preimage.unpack('C*'),
+                                    signature: sig_bytes,
+                                    protocol_id: PROTOCOL_ID,
+                                    key_id: "#{cert[:type]} #{cert[:serial_number]}",
+                                    counterparty: cert[:certifier]
+                                  })
+
+        true
+      rescue InvalidSignatureError => e
+        raise if e.is_a?(InvalidError)
+
+        raise InvalidError, e.message
+      rescue ArgumentError, EncodingError => e
+        # EncodingError covers Encoding::InvalidByteSequenceError and
+        # Encoding::UndefinedConversionError, which `encode_fields`
+        # raises for non-UTF-8 field names or values. Callers of
+        # `acquire_certificate` expect `InvalidError` on bad cert input
+        # — leaking EncodingError would break that contract.
+        raise InvalidError, e.message
+      end
+
+      # Build the BRC-52 canonical preimage for signing or verifying.
+      #
+      # @param cert [Hash] certificate fields (see {.verify!})
+      # @return [String] binary string suitable for +sha256+ (via
+      #   {ProtoWallet#verify_signature})
+      def serialise_preimage(cert)
+        buf = String.new(encoding: Encoding::ASCII_8BIT)
+        buf << decode_base64_exact(cert[:type], 32, 'type')
+        buf << decode_base64_exact(cert[:serial_number], 32, 'serial_number')
+        buf << decode_hex_exact(cert[:subject], 33, 'subject')
+        buf << decode_hex_exact(cert[:certifier], 33, 'certifier')
+
+        buf << encode_revocation_outpoint(cert[:revocation_outpoint])
+        buf << encode_fields(cert[:fields])
+        buf
+      end
+
+      class << self
+        private
+
+        def encode_revocation_outpoint(outpoint)
+          raise ArgumentError, 'revocation_outpoint is missing' if outpoint.nil? || outpoint.empty?
+
+          txid_hex, output_index_str = outpoint.to_s.split('.', 2)
+          raise ArgumentError, "revocation_outpoint #{outpoint.inspect} missing '.<output_index>'" if output_index_str.nil?
+
+          unless output_index_str.match?(/\A\d+\z/)
+            raise ArgumentError, "revocation_outpoint output index must be a non-negative integer, got #{output_index_str.inspect}"
+          end
+
+          buf = String.new(encoding: Encoding::ASCII_8BIT)
+          buf << decode_hex_exact(txid_hex, 32, 'revocation_outpoint txid')
+          buf << BSV::Transaction::VarInt.encode(output_index_str.to_i)
+          buf
+        end
+
+        def encode_fields(fields)
+          raise ArgumentError, 'fields must be a Hash' unless fields.is_a?(Hash)
+
+          normalised = normalise_field_keys(fields)
+
+          buf = String.new(encoding: Encoding::ASCII_8BIT)
+          sorted_names = normalised.keys.sort
+          buf << BSV::Transaction::VarInt.encode(sorted_names.length)
+
+          sorted_names.each do |name|
+            name_bytes = name.encode('UTF-8').b
+            value_bytes = normalised[name].to_s.encode('UTF-8').b
+
+            buf << BSV::Transaction::VarInt.encode(name_bytes.bytesize)
+            buf << name_bytes
+            buf << BSV::Transaction::VarInt.encode(value_bytes.bytesize)
+            buf << value_bytes
+          end
+          buf
+        end
+
+        # Normalise Hash keys to strings and reject post-normalisation
+        # duplicates (e.g. both `:email` and `'email'`). Without this,
+        # `fields.keys.map(&:to_s)` silently produces duplicate entries
+        # with ambiguous value ordering, which makes the BRC-52 preimage
+        # non-deterministic.
+        def normalise_field_keys(fields)
+          normalised = {}
+          fields.each do |key, value|
+            str_key = key.to_s
+            if normalised.key?(str_key)
+              raise ArgumentError,
+                    "duplicate field name #{str_key.inspect} " \
+                    '(once as string, once as symbol)'
+            end
+
+            normalised[str_key] = value
+          end
+          normalised
+        end
+
+        def decode_base64_exact(value, expected_length, field_name)
+          raise ArgumentError, "#{field_name} is missing" if value.nil? || value.empty?
+
+          # strict_decode64 (vs permissive decode64) rejects whitespace,
+          # non-base64 characters, and non-canonical padding. The rest
+          # of bsv-wallet (e.g. the wire serialiser) uses strict mode,
+          # and the BRC-52 preimage must be unambiguous — a cert with
+          # whitespace-injected type/serial_number would decode to the
+          # right length but produce a different canonical form than
+          # the same data re-submitted cleanly.
+          bytes = begin
+            Base64.strict_decode64(value)
+          rescue ArgumentError => e
+            raise ArgumentError, "#{field_name} is not valid base64: #{e.message}"
+          end
+
+          if bytes.bytesize != expected_length
+            raise ArgumentError,
+                  "#{field_name} must decode to #{expected_length} bytes, got #{bytes.bytesize}"
+          end
+
+          bytes.b
+        end
+
+        def decode_hex_exact(value, expected_length, field_name)
+          raise ArgumentError, "#{field_name} is missing" if value.nil? || value.empty?
+          raise ArgumentError, "#{field_name} must be a hex string" unless value.match?(/\A\h+\z/)
+          raise ArgumentError, "#{field_name} hex length must be even" unless value.length.even?
+
+          bytes = [value].pack('H*')
+          if bytes.bytesize != expected_length
+            raise ArgumentError,
+                  "#{field_name} must decode to #{expected_length} bytes, got #{bytes.bytesize}"
+          end
+
+          bytes.b
+        end
+
+        def hex_to_bytes(hex)
+          raise ArgumentError, 'signature must be a hex string' unless hex.is_a?(String) && hex.match?(/\A\h+\z/)
+          raise ArgumentError, 'signature hex length must be even' unless hex.length.even?
+
+          [hex].pack('H*').unpack('C*')
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.3.3'
+    VERSION = '0.3.4'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -803,7 +803,7 @@ module BSV
       end
 
       def acquire_via_direct(args)
-        {
+        cert = {
           type: args[:type],
           subject: @key_deriver.identity_key,
           serial_number: args[:serial_number],
@@ -813,6 +813,15 @@ module BSV
           fields: args[:fields],
           keyring: args[:keyring_for_subject]
         }
+
+        # BRC-52: verify the certifier's signature against the canonical
+        # serialisation before persisting. Fixes F8.15 from the 2026-04-08
+        # cross-SDK compliance review (#305) — prior to this check, callers
+        # could pass any value in `args[:signature]` and it would be stored
+        # as if certifier-authentic.
+        CertificateSignature.verify!(cert)
+
+        cert
       end
 
       def acquire_via_issuance(args)
@@ -833,7 +842,7 @@ module BSV
 
         body = JSON.parse(response.body)
 
-        {
+        cert = {
           type: body['type'] || args[:type],
           subject: @key_deriver.identity_key,
           serial_number: body['serialNumber'],
@@ -843,6 +852,14 @@ module BSV
           fields: body['fields'] || args[:fields],
           keyring: body['keyringForSubject']
         }
+
+        # BRC-52: the certifier's HTTP response is untrusted network data;
+        # verify the signature before persisting. Closes the F8.15 class of
+        # bug on the issuance path too (the finding's "Same issue as F8.15"
+        # note from F8.16).
+        CertificateSignature.verify!(cert)
+
+        cert
       rescue JSON::ParserError
         raise WalletError, 'Certificate issuance failed: invalid JSON response'
       end

data/lib/bsv/wallet_interface.rb

@@ -20,6 +20,7 @@ module BSV
     autoload :NullChainProvider, 'bsv/wallet_interface/null_chain_provider'
     autoload :WalletClient,      'bsv/wallet_interface/wallet_client'
     autoload :Wire,              'bsv/wallet_interface/wire'
+    autoload :CertificateSignature, 'bsv/wallet_interface/certificate_signature'
 
     # Error classes
     autoload :WalletError,            'bsv/wallet_interface/errors/wallet_error'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -27,16 +27,22 @@ dependencies:
   name: bsv-sdk
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.2
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.2
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1.0'
 description: Implements the BRC-100 standard wallet-to-application interface for the
   BSV Blockchain.
 executables: []
@@ -46,6 +52,7 @@ files:
 - LICENSE
 - lib/bsv-wallet.rb
 - lib/bsv/wallet_interface.rb
+- lib/bsv/wallet_interface/certificate_signature.rb
 - lib/bsv/wallet_interface/chain_provider.rb
 - lib/bsv/wallet_interface/errors/invalid_hmac_error.rb
 - lib/bsv/wallet_interface/errors/invalid_parameter_error.rb