bsv-wallet 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6224c4f914180b05509cd15454a22709ebc899b72e6ba3c77fdace1a8005e125
-  data.tar.gz: 5bbcb406a15c15d02c2181b54cebfdb6b6e27bfd3f56ecf90adc7e3d5e1e2cce
+  metadata.gz: 42266cef3c2585982df666f123097ea4fb4edd9f6619aacf37ed50628148ae1f
+  data.tar.gz: cec92d7893bba6a8b25439f5fd9c4d203ae7fce0cc2f63370adfc1a01d6bed61
 SHA512:
-  metadata.gz: b76c12653644732d2283fcc452a2a5c3a509d776cb510c261fcb13f9a396dba40de40d2dae2bfa321dc1d79df0e8b702c0b62b7b546b4f31588f9e4f14c7f161
-  data.tar.gz: 502dde3dfd72aea6089939284e39c8d00d1e4d7b52d1dd260de68c37a39c156d0bad88a4cfbd16bbb1d5ec5211110e75c2c836763cffdb10b433685d63301539
+  metadata.gz: b45b5c376c8c2b20ec7afffd1f57a15e89d19509ad6afecce8da8f3cdd69b9f7d8af20b5157ca380b8d0a65d9db5dc9a6aed2b8ac1518542775207534e576825
+  data.tar.gz: aae7eaec036fd2bd620551645e5a111bccfa39ac948ccb6541f24dc5e187acd1c9458a2576b4bca3adc5e31c0ec73d83af270cee8861d940af9952da429fe36c

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/file_store.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'logger'
+
+module BSV
+  module Wallet
+    # JSON file-backed storage adapter.
+    #
+    # Persists actions, outputs, and certificates as JSON files in a
+    # configurable directory (default: +~/.bsv-wallet/+). Data survives
+    # process restarts.
+    #
+    # Inherits all filtering and pagination logic from {MemoryStore} and
+    # adds load-on-init / save-on-mutation.
+    #
+    # @example Default location
+    #   store = BSV::Wallet::FileStore.new
+    #   # Data written to ~/.bsv-wallet/
+    #
+    # @example Custom directory
+    #   store = BSV::Wallet::FileStore.new(dir: '/var/lib/my-app/wallet')
+    class FileStore < MemoryStore
+      DEFAULT_DIR = File.expand_path('~/.bsv-wallet')
+
+      # @param dir [String] directory for JSON files
+      #   (default: +~/.bsv-wallet/+ or +BSV_WALLET_DIR+ env var)
+      # @param dir [String] directory for JSON files
+      # @param logger [Logger, nil] logger for permission warnings (default: Logger to STDERR)
+      def initialize(dir: nil, logger: nil)
+        super()
+        @dir = dir || ENV.fetch('BSV_WALLET_DIR', DEFAULT_DIR)
+        @logger = logger || Logger.new($stderr, progname: 'bsv-wallet')
+        FileUtils.mkdir_p(@dir, mode: 0o700)
+        check_permissions
+        load_from_disk
+      end
+
+      # @return [String] the storage directory path
+      attr_reader :dir
+
+      # --- Mutations: delegate to super, then persist ---
+
+      def store_action(action_data)
+        result = super
+        save_actions
+        result
+      end
+
+      def store_output(output_data)
+        result = super
+        save_outputs
+        result
+      end
+
+      def delete_output(outpoint)
+        result = super
+        save_outputs if result
+        result
+      end
+
+      def store_certificate(cert_data)
+        result = super
+        save_certificates
+        result
+      end
+
+      def delete_certificate(type:, serial_number:, certifier:)
+        result = super
+        save_certificates if result
+        result
+      end
+
+      private
+
+      def check_permissions
+        dir_mode = File.stat(@dir).mode & 0o777
+        if dir_mode != 0o700
+          @logger.warn("Wallet directory #{@dir} has permissions #{format('%04o', dir_mode)} (expected 0700). " \
+                       'Other users may be able to access wallet data.')
+        end
+
+        [actions_path, outputs_path, certificates_path].each do |path|
+          next unless File.exist?(path)
+
+          file_mode = File.stat(path).mode & 0o777
+          next if file_mode == 0o600
+
+          @logger.warn("Wallet file #{path} has permissions #{format('%04o', file_mode)} (expected 0600). " \
+                       'Other users may be able to read wallet data.')
+        end
+      end
+
+      def actions_path
+        File.join(@dir, 'actions.json')
+      end
+
+      def outputs_path
+        File.join(@dir, 'outputs.json')
+      end
+
+      def certificates_path
+        File.join(@dir, 'certificates.json')
+      end
+
+      def load_from_disk
+        @actions = load_file(actions_path)
+        @outputs = load_file(outputs_path)
+        @certificates = load_file(certificates_path)
+      end
+
+      def load_file(path)
+        return [] unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        return [] unless data.is_a?(Array)
+
+        # Symbolise top-level keys for consistency with MemoryStore
+        data.map { |entry| symbolise_keys(entry) }
+      rescue JSON::ParserError
+        []
+      end
+
+      def save_actions
+        write_file(actions_path, @actions)
+      end
+
+      def save_outputs
+        write_file(outputs_path, @outputs)
+      end
+
+      def save_certificates
+        write_file(certificates_path, @certificates)
+      end
+
+      def write_file(path, data)
+        json = JSON.pretty_generate(stringify_keys_deep(data))
+        tmp = "#{path}.tmp"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(json) }
+        File.rename(tmp, path)
+      end
+
+      def symbolise_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(k, v), result|
+          result[k.to_sym] = case v
+                             when Hash then symbolise_keys(v)
+                             when Array then v.map { |e| e.is_a?(Hash) ? symbolise_keys(e) : e }
+                             else v
+                             end
+        end
+      end
+
+      def stringify_keys_deep(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), result|
+            result[k.to_s] = stringify_keys_deep(v)
+          end
+        when Array
+          obj.map { |e| stringify_keys_deep(e) }
+        else
+          obj
+        end
+      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.2.0'
   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,24 @@ 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 storage [StorageAdapter] persistence adapter (default: FileStore).
+      #   Use +storage: MemoryStore.new+ for tests.
+      # @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: FileStore.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 +182,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 +708,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