bsv-wallet 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6224c4f914180b05509cd15454a22709ebc899b72e6ba3c77fdace1a8005e125
-  data.tar.gz: 5bbcb406a15c15d02c2181b54cebfdb6b6e27bfd3f56ecf90adc7e3d5e1e2cce
+  metadata.gz: 4b8425ff5a48801f390149006396bac80983a36231e101ff9e96255b4c702f68
+  data.tar.gz: 5df7b47ab142634281a76a68de73cd30562a31c4864cddb1ebf5cfe332e60ac0
 SHA512:
-  metadata.gz: b76c12653644732d2283fcc452a2a5c3a509d776cb510c261fcb13f9a396dba40de40d2dae2bfa321dc1d79df0e8b702c0b62b7b546b4f31588f9e4f14c7f161
-  data.tar.gz: 502dde3dfd72aea6089939284e39c8d00d1e4d7b52d1dd260de68c37a39c156d0bad88a4cfbd16bbb1d5ec5211110e75c2c836763cffdb10b433685d63301539
+  metadata.gz: 7a8faf79916348e238b86b1006a78cf16ce4bcc0317170c7bd0ba80a2627615a129b6b2a694af884a2492379a29f354994581cd74e54adc62cd6138103906094
+  data.tar.gz: 9f3f53a96072ed5dd27d46265a54558b3bd8073811d7532458276d4d287f59c5b77714017d024f970b95686f7fca8c1f5fc0891ba32e493cb671287ac84ff74c

data/lib/bsv/wallet_interface/chain_provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Duck-typed interface for blockchain data providers.
+    #
+    # Include this module in chain provider adapters and override all methods.
+    # The default implementations raise NotImplementedError.
+    #
+    # @example Custom provider
+    #   class MyChainProvider
+    #     include BSV::Wallet::ChainProvider
+    #
+    #     def get_height
+    #       # query your node/API
+    #     end
+    #
+    #     def get_header(height)
+    #       # return 80-byte hex block header
+    #     end
+    #   end
+    module ChainProvider
+      # Returns the current blockchain height.
+      # @return [Integer]
+      def get_height
+        raise NotImplementedError, "#{self.class}#get_height not implemented"
+      end
+
+      # Returns the block header at the given height.
+      # @param _height [Integer] block height
+      # @return [String] 80-byte hex-encoded block header
+      def get_header(_height)
+        raise NotImplementedError, "#{self.class}#get_header not implemented"
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/memory_store.rb

@@ -55,10 +55,11 @@ module BSV
       end
 
       def find_certificates(query)
-        results = @certificates
-        results = results.select { |c| query[:certifiers].include?(c[:certifier]) } if query[:certifiers]
-        results = results.select { |c| query[:types].include?(c[:type]) } if query[:types]
-        apply_pagination(results, query)
+        apply_pagination(filter_certificates(query), query)
+      end
+
+      def count_certificates(query)
+        filter_certificates(query).length
       end
 
       def delete_certificate(type:, serial_number:, certifier:)
@@ -105,6 +106,20 @@ module BSV
         query[:include_spent] ? results : results.reject { |o| o[:spendable] == false }
       end
 
+      def filter_certificates(query)
+        results = @certificates
+        results = results.select { |c| query[:certifiers].include?(c[:certifier]) } if query[:certifiers]
+        results = results.select { |c| query[:types].include?(c[:type]) } if query[:types]
+        results = results.select { |c| c[:subject] == query[:subject] } if query[:subject]
+        if query[:attributes]
+          results = results.select do |c|
+            fields = c[:fields] || {}
+            query[:attributes].all? { |k, v| fields[k] == v || fields[k.to_sym] == v }
+          end
+        end
+        results
+      end
+
       def apply_pagination(results, query)
         offset = query[:offset] || 0
         limit = query[:limit] || 10

data/lib/bsv/wallet_interface/null_chain_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Default chain provider that raises for all blockchain queries.
+    #
+    # Used when a WalletClient is constructed without a chain provider,
+    # allowing the wallet to function for transaction and crypto operations
+    # without requiring a blockchain connection.
+    class NullChainProvider
+      include ChainProvider
+
+      def get_height
+        raise UnsupportedActionError, 'get_height (no chain provider configured)'
+      end
+
+      def get_header(_height)
+        raise UnsupportedActionError, 'get_header_for_height (no chain provider configured)'
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/storage_adapter.rb

@@ -46,6 +46,10 @@ module BSV
       def count_outputs(_query)
         raise NotImplementedError, "#{self.class}#count_outputs not implemented"
       end
+
+      def count_certificates(_query)
+        raise NotImplementedError, "#{self.class}#count_certificates not implemented"
+      end
     end
   end
 end

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -2,6 +2,9 @@
 
 require 'securerandom'
 require 'base64'
+require 'net/http'
+require 'json'
+require 'uri'
 
 module BSV
   module Wallet
@@ -26,11 +29,23 @@ module BSV
       # @return [StorageAdapter] the underlying persistence adapter
       attr_reader :storage
 
+      # @return [ChainProvider] the blockchain data provider
+      attr_reader :chain_provider
+
+      # @return [String] the network ('mainnet' or 'testnet')
+      attr_reader :network
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
       # @param storage [StorageAdapter] persistence adapter (default: MemoryStore)
-      def initialize(key, storage: MemoryStore.new)
+      # @param network [String] 'mainnet' (default) or 'testnet'
+      # @param chain_provider [ChainProvider] blockchain data provider (default: NullChainProvider)
+      # @param http_client [#request, nil] injectable HTTP client for certificate issuance
+      def initialize(key, storage: MemoryStore.new, network: 'mainnet', chain_provider: NullChainProvider.new, http_client: nil)
         super(key)
         @storage = storage
+        @network = network
+        @chain_provider = chain_provider
+        @http_client = http_client
         @pending = {}
       end
 
@@ -166,6 +181,217 @@ module BSV
         { accepted: true }
       end
 
+      # --- Blockchain & Network Data ---
+
+      # Returns the current blockchain height from the chain provider.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { height: Integer }
+      def get_height(_args = {}, _originator: nil)
+        { height: @chain_provider.get_height }
+      end
+
+      # Returns the block header at the given height from the chain provider.
+      #
+      # @param args [Hash]
+      # @option args [Integer] :height block height
+      # @return [Hash] { header: String } 80-byte hex-encoded block header
+      def get_header_for_height(args, _originator: nil)
+        raise InvalidParameterError.new('height', 'a positive Integer') unless args[:height].is_a?(Integer) && args[:height].positive?
+
+        { header: @chain_provider.get_header(args[:height]) }
+      end
+
+      # Returns the network this wallet is configured for.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { network: String } 'mainnet' or 'testnet'
+      def get_network(_args = {}, _originator: nil)
+        { network: @network }
+      end
+
+      # Returns the wallet version string.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { version: String } in vendor-major.minor.patch format
+      def get_version(_args = {}, _originator: nil)
+        { version: "bsv-wallet-#{BSV::WalletInterface::VERSION}" }
+      end
+
+      # --- Authentication ---
+
+      # Checks whether the user is authenticated.
+      # For local wallets with a private key, this is always true.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { authenticated: Boolean }
+      def is_authenticated(_args = {}, _originator: nil)
+        { authenticated: true }
+      end
+
+      # Waits until the user is authenticated.
+      # For local wallets, returns immediately.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { authenticated: true }
+      def wait_for_authentication(_args = {}, _originator: nil)
+        { authenticated: true }
+      end
+
+      # --- Identity and Certificate Management ---
+
+      # Acquires an identity certificate via direct storage.
+      #
+      # The 'issuance' protocol (which requires HTTP to a certifier URL) is
+      # not yet supported and raises {UnsupportedActionError}.
+      #
+      # @param args [Hash]
+      # @option args [String] :type certificate type (base64)
+      # @option args [String] :certifier certifier public key hex
+      # @option args [String] :acquisition_protocol 'direct' or 'issuance'
+      # @option args [Hash] :fields certificate fields (field_name => value)
+      # @option args [String] :serial_number serial number (required for direct)
+      # @option args [String] :revocation_outpoint outpoint string (required for direct)
+      # @option args [String] :signature certifier signature hex (required for direct)
+      # @option args [String] :keyring_revealer pubkey hex or 'certifier' (required for direct)
+      # @option args [Hash] :keyring_for_subject field_name => base64 key (required for direct)
+      # @return [Hash] the stored certificate
+      def acquire_certificate(args, _originator: nil)
+        validate_acquire_certificate!(args)
+
+        cert = if args[:acquisition_protocol] == 'issuance'
+                 acquire_via_issuance(args)
+               else
+                 acquire_via_direct(args)
+               end
+
+        @storage.store_certificate(cert)
+        cert_without_keyring(cert)
+      end
+
+      # Lists identity certificates filtered by certifier and type.
+      #
+      # @param args [Hash]
+      # @option args [Array<String>] :certifiers certifier public keys
+      # @option args [Array<String>] :types certificate types
+      # @option args [Integer] :limit max results (default 10)
+      # @option args [Integer] :offset number to skip (default 0)
+      # @return [Hash] { total_certificates:, certificates: [...] }
+      def list_certificates(args, _originator: nil)
+        raise InvalidParameterError.new('certifiers', 'a non-empty Array') unless args[:certifiers].is_a?(Array) && !args[:certifiers].empty?
+        raise InvalidParameterError.new('types', 'a non-empty Array') unless args[:types].is_a?(Array) && !args[:types].empty?
+
+        query = {
+          certifiers: args[:certifiers],
+          types: args[:types],
+          limit: args[:limit] || 10,
+          offset: args[:offset] || 0
+        }
+        total = @storage.count_certificates(query)
+        certs = @storage.find_certificates(query)
+        { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
+      end
+
+      # Proves select fields of an identity certificate to a verifier.
+      #
+      # Encrypts each requested field's keyring entry for the verifier using
+      # protocol-derived encryption (BRC-2), allowing the verifier to decrypt
+      # only the revealed fields.
+      #
+      # @param args [Hash]
+      # @option args [Hash] :certificate the certificate to prove
+      # @option args [Array<String>] :fields_to_reveal field names to reveal
+      # @option args [String] :verifier verifier public key hex
+      # @return [Hash] { keyring_for_verifier: { field_name => Array<Integer> } }
+      def prove_certificate(args, _originator: nil)
+        cert_arg = args[:certificate]
+        fields_to_reveal = args[:fields_to_reveal]
+        verifier = args[:verifier]
+
+        raise InvalidParameterError.new('certificate', 'a Hash') unless cert_arg.is_a?(Hash)
+        raise InvalidParameterError.new('fields_to_reveal', 'a non-empty Array') unless fields_to_reveal.is_a?(Array) && !fields_to_reveal.empty?
+
+        Validators.validate_pub_key_hex!(verifier, 'verifier')
+
+        # Look up the full certificate (with keyring) from storage
+        stored = find_stored_certificate(cert_arg)
+        raise WalletError, 'Certificate not found in wallet' unless stored
+        raise WalletError, 'Certificate has no keyring' unless stored[:keyring]
+
+        keyring_for_verifier = {}
+        fields_to_reveal.each do |field_name|
+          key_value = stored[:keyring][field_name] || stored[:keyring][field_name.to_sym]
+          raise WalletError, "Keyring entry not found for field '#{field_name}'" unless key_value
+
+          # Encrypt the keyring entry for the verifier
+          encrypted = encrypt({
+                                plaintext: key_value.bytes,
+                                protocol_id: [2, 'certificate field revelation'],
+                                key_id: "#{cert_arg[:type]} #{cert_arg[:serial_number]} #{field_name}",
+                                counterparty: verifier
+                              })
+          keyring_for_verifier[field_name] = encrypted[:ciphertext]
+        end
+
+        { keyring_for_verifier: keyring_for_verifier }
+      end
+
+      # Removes a certificate from the wallet.
+      #
+      # @param args [Hash]
+      # @option args [String] :type certificate type
+      # @option args [String] :serial_number serial number
+      # @option args [String] :certifier certifier public key hex
+      # @return [Hash] { relinquished: true }
+      def relinquish_certificate(args, _originator: nil)
+        deleted = @storage.delete_certificate(
+          type: args[:type],
+          serial_number: args[:serial_number],
+          certifier: args[:certifier]
+        )
+        raise WalletError, 'Certificate not found' unless deleted
+
+        { relinquished: true }
+      end
+
+      # Discovers certificates issued to a given identity key.
+      #
+      # For a local wallet, searches stored certificates where the subject
+      # matches the given identity key.
+      #
+      # @param args [Hash]
+      # @option args [String] :identity_key public key hex to search
+      # @option args [Integer] :limit max results (default 10)
+      # @option args [Integer] :offset number to skip (default 0)
+      # @return [Hash] { total_certificates:, certificates: [...] }
+      def discover_by_identity_key(args, _originator: nil)
+        Validators.validate_pub_key_hex!(args[:identity_key], 'identity_key')
+
+        query = { subject: args[:identity_key], limit: args[:limit] || 10, offset: args[:offset] || 0 }
+        total = @storage.count_certificates(query)
+        certs = @storage.find_certificates(query)
+        { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
+      end
+
+      # Discovers certificates matching specific attribute values.
+      #
+      # Searches stored certificates where field values match the given
+      # attributes. Only searches certificates belonging to this wallet.
+      #
+      # @param args [Hash]
+      # @option args [Hash] :attributes field_name => value pairs to match
+      # @option args [Integer] :limit max results (default 10)
+      # @option args [Integer] :offset number to skip (default 0)
+      # @return [Hash] { total_certificates:, certificates: [...] }
+      def discover_by_attributes(args, _originator: nil)
+        raise InvalidParameterError.new('attributes', 'a non-empty Hash') unless args[:attributes].is_a?(Hash) && !args[:attributes].empty?
+
+        query = { attributes: args[:attributes], limit: args[:limit] || 10, offset: args[:offset] || 0 }
+        total = @storage.count_certificates(query)
+        certs = @storage.find_certificates(query)
+        { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
+      end
+
       private
 
       # --- Validation ---
@@ -481,6 +707,97 @@ module BSV
                                 spendable: true
                               })
       end
+
+      # --- Certificate helpers ---
+
+      def validate_acquire_certificate!(args)
+        raise InvalidParameterError.new('type', 'a String') unless args[:type].is_a?(String)
+
+        Validators.validate_pub_key_hex!(args[:certifier], 'certifier')
+        raise InvalidParameterError.new('fields', 'a Hash') unless args[:fields].is_a?(Hash)
+
+        protocol = args[:acquisition_protocol]
+        raise InvalidParameterError.new('acquisition_protocol', '"direct" or "issuance"') unless %w[direct issuance].include?(protocol)
+
+        if protocol == 'direct'
+          raise InvalidParameterError.new('serial_number', 'present for direct acquisition') unless args[:serial_number]
+          raise InvalidParameterError.new('revocation_outpoint', 'present for direct acquisition') unless args[:revocation_outpoint]
+          raise InvalidParameterError.new('signature', 'present for direct acquisition') unless args[:signature]
+          raise InvalidParameterError.new('keyring_for_subject', 'a Hash for direct acquisition') unless args[:keyring_for_subject].is_a?(Hash)
+        elsif protocol == 'issuance'
+          raise InvalidParameterError.new('certifier_url', 'present for issuance acquisition') unless args[:certifier_url].is_a?(String)
+        end
+      end
+
+      def acquire_via_direct(args)
+        {
+          type: args[:type],
+          subject: @key_deriver.identity_key,
+          serial_number: args[:serial_number],
+          certifier: args[:certifier],
+          revocation_outpoint: args[:revocation_outpoint],
+          signature: args[:signature],
+          fields: args[:fields],
+          keyring: args[:keyring_for_subject]
+        }
+      end
+
+      def acquire_via_issuance(args)
+        uri = URI(args[:certifier_url])
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate({
+                                       type: args[:type],
+                                       subject: @key_deriver.identity_key,
+                                       certifier: args[:certifier],
+                                       fields: args[:fields]
+                                     })
+
+        response = execute_http(uri, request)
+        code = response.code.to_i
+
+        raise WalletError, "Certificate issuance failed: HTTP #{code}" unless (200..299).cover?(code)
+
+        body = JSON.parse(response.body)
+
+        {
+          type: body['type'] || args[:type],
+          subject: @key_deriver.identity_key,
+          serial_number: body['serialNumber'],
+          certifier: args[:certifier],
+          revocation_outpoint: body['revocationOutpoint'],
+          signature: body['signature'],
+          fields: body['fields'] || args[:fields],
+          keyring: body['keyringForSubject']
+        }
+      rescue JSON::ParserError
+        raise WalletError, 'Certificate issuance failed: invalid JSON response'
+      end
+
+      def execute_http(uri, request)
+        if @http_client
+          @http_client.request(uri, request)
+        else
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+            http.request(request)
+          end
+        end
+      end
+
+      def find_stored_certificate(cert_arg)
+        results = @storage.find_certificates({
+                                               certifiers: [cert_arg[:certifier]],
+                                               types: [cert_arg[:type]],
+                                               limit: 10_000
+                                             })
+        results.find { |c| c[:serial_number] == cert_arg[:serial_number] }
+      end
+
+      def cert_without_keyring(cert)
+        result = cert.dup
+        result.delete(:keyring)
+        result
+      end
     end
   end
 end