bsv-sdk 0.7.0 → 0.8.0

data/lib/bsv/wallet_interface/proto_wallet.rb

@@ -1,361 +0,0 @@
-# frozen_string_literal: true
-
-require 'openssl'
-
-module BSV
-  module Wallet
-    # Cryptographic wallet implementing the 8 key/crypto BRC-100 methods.
-    #
-    # ProtoWallet handles key derivation, encryption, decryption, HMAC,
-    # and signature operations using BRC-42/43 key derivation. Transaction,
-    # certificate, blockchain, and authentication methods raise
-    # {UnsupportedActionError} via the included {Interface}.
-    #
-    # @example Encrypt and decrypt a message
-    #   wallet = BSV::Wallet::ProtoWallet.new(BSV::Primitives::PrivateKey.generate)
-    #   args = { protocol_id: [0, 'hello world'], key_id: '1', counterparty: 'self' }
-    #   result = wallet.encrypt(args.merge(plaintext: [104, 101, 108, 108, 111]))
-    #   wallet.decrypt(args.merge(ciphertext: result[:ciphertext]))[:plaintext]
-    class ProtoWallet
-      include Interface
-
-      # @return [KeyDeriver] the underlying key deriver
-      attr_reader :key_deriver
-
-      # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver]
-      #   A private key, the string +'anyone'+, or a pre-built {KeyDeriver}
-      def initialize(key)
-        @key_deriver = if key.is_a?(KeyDeriver)
-                         key
-                       else
-                         KeyDeriver.new(key)
-                       end
-      end
-
-      # Returns a derived or identity public key.
-      #
-      # When +args[:identity_key]+ is true, returns the wallet's identity key.
-      # Otherwise derives a key for the given protocol, key ID, and counterparty.
-      #
-      # @param args [Hash]
-      # @option args [Boolean] :identity_key return the identity key instead of deriving
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @option args [Boolean] :for_self derive from own identity
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { public_key: String } hex-encoded compressed public key
-      def get_public_key(args, originator: nil)
-        if args[:identity_key]
-          { public_key: @key_deriver.identity_key }
-        else
-          counterparty = args[:counterparty] || 'self'
-          pub = @key_deriver.derive_public_key(
-            args[:protocol_id],
-            args[:key_id],
-            counterparty,
-            for_self: args[:for_self] || false
-          )
-          { public_key: pub.to_hex }
-        end
-      end
-
-      # Encrypts plaintext using AES-256-GCM with a derived symmetric key.
-      #
-      # @param args [Hash]
-      # @option args [Array<Integer>] :plaintext byte array to encrypt
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { ciphertext: Array<Integer> }
-      def encrypt(args, originator: nil)
-        sym_key = derive_sym_key(args)
-        ciphertext = sym_key.encrypt(bytes_to_string(args[:plaintext]))
-        { ciphertext: string_to_bytes(ciphertext) }
-      end
-
-      # Decrypts ciphertext using AES-256-GCM with a derived symmetric key.
-      #
-      # @param args [Hash]
-      # @option args [Array<Integer>] :ciphertext byte array to decrypt
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { plaintext: Array<Integer> }
-      def decrypt(args, originator: nil)
-        sym_key = derive_sym_key(args)
-        plaintext = sym_key.decrypt(bytes_to_string(args[:ciphertext]))
-        { plaintext: string_to_bytes(plaintext) }
-      end
-
-      # Creates an HMAC-SHA256 using a derived symmetric key.
-      #
-      # @param args [Hash]
-      # @option args [Array<Integer>] :data byte array to authenticate
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { hmac: Array<Integer> }
-      def create_hmac(args, originator: nil)
-        sym_key = derive_sym_key(args)
-        hmac = BSV::Primitives::Digest.hmac_sha256(sym_key.to_bytes, bytes_to_string(args[:data]))
-        { hmac: string_to_bytes(hmac) }
-      end
-
-      # Verifies an HMAC-SHA256 using a derived symmetric key.
-      #
-      # @param args [Hash]
-      # @option args [Array<Integer>] :data byte array that was authenticated
-      # @option args [Array<Integer>] :hmac HMAC to verify
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { valid: true }
-      # @raise [InvalidHmacError] if the HMAC does not match
-      def verify_hmac(args, originator: nil)
-        sym_key = derive_sym_key(args)
-        expected = BSV::Primitives::Digest.hmac_sha256(sym_key.to_bytes, bytes_to_string(args[:data]))
-        provided = bytes_to_string(args[:hmac])
-
-        raise InvalidHmacError unless secure_compare(expected, provided)
-
-        { valid: true }
-      end
-
-      # Creates an ECDSA signature using a derived private key.
-      #
-      # Either +:data+ or +:hash_to_directly_sign+ must be provided.
-      # If +:data+ is given it is SHA-256 hashed before signing.
-      # If +:hash_to_directly_sign+ is given it is used as the 32-byte hash directly.
-      #
-      # @param args [Hash]
-      # @option args [Array<Integer>] :data data to hash and sign
-      # @option args [Array<Integer>] :hash_to_directly_sign pre-computed 32-byte hash to sign
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { signature: Array<Integer> } DER-encoded signature as byte array
-      def create_signature(args, originator: nil)
-        counterparty = args[:counterparty] || 'self'
-        priv_key = @key_deriver.derive_private_key(args[:protocol_id], args[:key_id], counterparty)
-
-        hash = if args[:hash_to_directly_sign]
-                 bytes_to_string(args[:hash_to_directly_sign])
-               else
-                 BSV::Primitives::Digest.sha256(bytes_to_string(args[:data]))
-               end
-
-        sig = priv_key.sign(hash)
-        { signature: string_to_bytes(sig.to_der) }
-      end
-
-      # Verifies an ECDSA signature using a derived public key.
-      #
-      # Either +:data+ or +:hash_to_directly_verify+ must be provided.
-      # If +:data+ is given it is SHA-256 hashed before verification.
-      #
-      # @param args [Hash]
-      # @option args [Array<Integer>] :data original data that was signed
-      # @option args [Array<Integer>] :hash_to_directly_verify pre-computed 32-byte hash
-      # @option args [Array<Integer>] :signature DER-encoded signature as byte array
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
-      # @option args [Boolean] :for_self verify own derived key (default false)
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] { valid: true }
-      # @raise [InvalidSignatureError] if the signature does not verify
-      def verify_signature(args, originator: nil)
-        counterparty = args[:counterparty] || 'self'
-        for_self = args[:for_self] || false
-
-        pub_key = @key_deriver.derive_public_key(
-          args[:protocol_id],
-          args[:key_id],
-          counterparty,
-          for_self: for_self
-        )
-
-        hash = if args[:hash_to_directly_verify]
-                 bytes_to_string(args[:hash_to_directly_verify])
-               else
-                 BSV::Primitives::Digest.sha256(bytes_to_string(args[:data]))
-               end
-
-        sig = BSV::Primitives::Signature.from_der(bytes_to_string(args[:signature]))
-        valid = pub_key.verify(hash, sig)
-
-        raise InvalidSignatureError unless valid
-
-        { valid: true }
-      end
-
-      # Reveals counterparty key linkage to a verifier (BRC-69 Method 1).
-      #
-      # Encrypts the ECDH shared secret between this wallet and the counterparty
-      # for the verifier using a BRC-72 protocol-derived key. Also generates a
-      # BRC-94 Schnorr zero-knowledge proof of the linkage and encrypts it for
-      # the verifier.
-      #
-      # @param args [Hash]
-      # @option args [String] :counterparty counterparty public key hex (not 'self')
-      # @option args [String] :verifier verifier public key hex
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] with :prover, :verifier, :counterparty, :revelation_time,
-      #   :encrypted_linkage, :encrypted_linkage_proof
-      def reveal_counterparty_key_linkage(args, originator: nil)
-        counterparty = args[:counterparty]
-        verifier = args[:verifier]
-
-        raise InvalidParameterError.new('counterparty', 'a specific public key hex, not "anyone"') if counterparty == 'anyone'
-
-        Validators.validate_pub_key_hex!(verifier, 'verifier')
-
-        linkage = @key_deriver.reveal_counterparty_secret(counterparty)
-        revelation_time = Time.now.utc.iso8601
-
-        encrypted_linkage_result = encrypt({
-                                             plaintext: string_to_bytes(linkage),
-                                             protocol_id: [2, 'counterparty linkage revelation'],
-                                             key_id: revelation_time,
-                                             counterparty: verifier
-                                           })
-
-        counterparty_pub = BSV::Primitives::PublicKey.from_hex(counterparty)
-        linkage_point = BSV::Primitives::PublicKey.from_bytes(linkage)
-        schnorr_proof = BSV::Primitives::Schnorr.generate_proof(
-          @key_deriver.root_key,
-          @key_deriver.root_key.public_key,
-          counterparty_pub,
-          linkage_point
-        )
-
-        z_bytes = schnorr_proof.z.to_s(2)
-        z_bytes = ("\x00".b * (32 - z_bytes.length)) + z_bytes if z_bytes.length < 32
-        proof_bin = schnorr_proof.r.compressed + schnorr_proof.s_prime.compressed + z_bytes
-
-        encrypted_proof_result = encrypt({
-                                           plaintext: string_to_bytes(proof_bin),
-                                           protocol_id: [2, 'counterparty linkage revelation'],
-                                           key_id: revelation_time,
-                                           counterparty: verifier
-                                         })
-
-        {
-          prover: @key_deriver.identity_key,
-          verifier: verifier,
-          counterparty: counterparty,
-          revelation_time: revelation_time,
-          encrypted_linkage: encrypted_linkage_result[:ciphertext],
-          encrypted_linkage_proof: encrypted_proof_result[:ciphertext]
-        }
-      end
-
-      # Reveals specific key linkage for a particular interaction (BRC-69 Method 2).
-      #
-      # Encrypts the HMAC-derived key offset for the given protocol/key combination
-      # for the verifier using a BRC-72 protocol-derived key. Proof type 0 means
-      # no cryptographic proof is provided (consistent with the ts-sdk behaviour).
-      #
-      # @param args [Hash]
-      # @option args [String] :counterparty counterparty public key hex
-      # @option args [String] :verifier verifier public key hex
-      # @option args [Array] :protocol_id [security_level, protocol_name]
-      # @option args [String] :key_id key identifier
-      # @param originator [String, nil] FQDN of the originating application
-      # @return [Hash] with :prover, :verifier, :counterparty, :protocol_id, :key_id,
-      #   :encrypted_linkage, :encrypted_linkage_proof, :proof_type
-      def reveal_specific_key_linkage(args, originator: nil)
-        counterparty = args[:counterparty]
-        verifier = args[:verifier]
-        protocol_id = args[:protocol_id]
-        key_id = args[:key_id]
-
-        raise InvalidParameterError.new('counterparty', 'a specific public key hex, not "anyone"') if counterparty == 'anyone'
-
-        Validators.validate_pub_key_hex!(verifier, 'verifier')
-
-        linkage = @key_deriver.reveal_specific_secret(counterparty, protocol_id, key_id)
-
-        derived_protocol = "specific linkage revelation #{protocol_id[0]} #{protocol_id[1]}"
-
-        encrypted_linkage_result = encrypt({
-                                             plaintext: string_to_bytes(linkage),
-                                             protocol_id: [2, derived_protocol],
-                                             key_id: key_id,
-                                             counterparty: verifier
-                                           })
-
-        encrypted_proof_result = encrypt({
-                                           plaintext: [0],
-                                           protocol_id: [2, derived_protocol],
-                                           key_id: key_id,
-                                           counterparty: verifier
-                                         })
-
-        {
-          prover: @key_deriver.identity_key,
-          verifier: verifier,
-          counterparty: counterparty,
-          protocol_id: protocol_id,
-          key_id: key_id,
-          encrypted_linkage: encrypted_linkage_result[:ciphertext],
-          encrypted_linkage_proof: encrypted_proof_result[:ciphertext],
-          proof_type: 0
-        }
-      end
-
-      private
-
-      # Derives a symmetric key from the args hash.
-      #
-      # @param args [Hash] must contain :protocol_id, :key_id; :counterparty defaults to 'self'
-      # @return [BSV::Primitives::SymmetricKey]
-      def derive_sym_key(args)
-        counterparty = args[:counterparty] || 'self'
-        @key_deriver.derive_symmetric_key(args[:protocol_id], args[:key_id], counterparty)
-      end
-
-      # Converts a byte array (Array of Integers 0..255) to a binary string.
-      #
-      # @param bytes [Array<Integer>] byte array
-      # @return [String] binary string
-      def bytes_to_string(bytes)
-        bytes.pack('C*')
-      end
-
-      # Converts a binary string to a byte array (Array of Integers 0..255).
-      #
-      # @param str [String] binary string
-      # @return [Array<Integer>] byte array
-      def string_to_bytes(str)
-        str.unpack('C*')
-      end
-
-      # Constant-time string comparison to prevent timing attacks.
-      #
-      # Falls back to a manual XOR loop on platforms where
-      # +OpenSSL.fixed_length_secure_compare+ is unavailable.
-      #
-      # @param a [String] first binary string
-      # @param b [String] second binary string
-      # @return [Boolean]
-      def secure_compare(a, b)
-        return false unless a.bytesize == b.bytesize
-
-        if OpenSSL.respond_to?(:fixed_length_secure_compare)
-          OpenSSL.fixed_length_secure_compare(a, b)
-        else
-          result = 0
-          a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
-          result.zero?
-        end
-      end
-    end
-  end
-end

data/lib/bsv/wallet_interface/storage_adapter.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    # Duck-typed storage interface for wallet persistence.
-    #
-    # Include this module in storage adapters and override all methods.
-    # The default implementations raise NotImplementedError.
-    module StorageAdapter
-      def store_action(_action_data)
-        raise NotImplementedError, "#{self.class}#store_action not implemented"
-      end
-
-      def find_actions(_query)
-        raise NotImplementedError, "#{self.class}#find_actions not implemented"
-      end
-
-      def store_output(_output_data)
-        raise NotImplementedError, "#{self.class}#store_output not implemented"
-      end
-
-      def find_outputs(_query)
-        raise NotImplementedError, "#{self.class}#find_outputs not implemented"
-      end
-
-      def delete_output(_outpoint)
-        raise NotImplementedError, "#{self.class}#delete_output not implemented"
-      end
-
-      def store_certificate(_cert_data)
-        raise NotImplementedError, "#{self.class}#store_certificate not implemented"
-      end
-
-      def find_certificates(_query)
-        raise NotImplementedError, "#{self.class}#find_certificates not implemented"
-      end
-
-      def delete_certificate(type:, serial_number:, certifier:)
-        raise NotImplementedError, "#{self.class}#delete_certificate not implemented"
-      end
-
-      def count_actions(_query)
-        raise NotImplementedError, "#{self.class}#count_actions not implemented"
-      end
-
-      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
-
-      def store_proof(_txid, _bump_hex)
-        raise NotImplementedError, "#{self.class}#store_proof not implemented"
-      end
-
-      def find_proof(_txid)
-        raise NotImplementedError, "#{self.class}#find_proof not implemented"
-      end
-
-      def store_transaction(_txid, _tx_hex)
-        raise NotImplementedError, "#{self.class}#store_transaction not implemented"
-      end
-
-      def find_transaction(_txid)
-        raise NotImplementedError, "#{self.class}#find_transaction not implemented"
-      end
-    end
-  end
-end

data/lib/bsv/wallet_interface/validators.rb

@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Wallet
-    module Validators
-      module_function
-
-      # BRC-100 protocol ID rules:
-      # - Array of [security_level, protocol_name]
-      # - security_level: Integer 0, 1, or 2
-      # - protocol_name: 5-400 chars (up to 430 for 'specific linkage revelation' protocol)
-      # - lowercase letters, numbers, and spaces only
-      # - no consecutive spaces
-      # - must not end with ' protocol'
-      # - must not start with 'admin' (BRC-44)
-      # - must not start with 'p ' (BRC-98 reserved)
-      def validate_protocol_id!(protocol_id)
-        unless protocol_id.is_a?(Array) && protocol_id.length == 2
-          raise InvalidParameterError.new('protocol_id',
-                                          'an Array of [security_level, protocol_name]')
-        end
-
-        level, name = protocol_id
-        raise InvalidParameterError.new('protocol_id security level', '0, 1, or 2') unless [0, 1, 2].include?(level)
-        raise InvalidParameterError.new('protocol_id name', 'a String') unless name.is_a?(String)
-
-        max_length = name.start_with?('specific linkage revelation') ? 430 : 400
-        raise InvalidParameterError.new('protocol_id name', "between 5 and #{max_length} characters") if name.length < 5 || name.length > max_length
-        raise InvalidParameterError.new('protocol_id name', 'lowercase letters, numbers, and spaces only') unless name.match?(/\A[a-z0-9 ]+\z/)
-        raise InvalidParameterError.new('protocol_id name', 'free of consecutive spaces') if name.include?('  ')
-        raise InvalidParameterError.new('protocol_id name', 'not ending with " protocol"') if name.end_with?(' protocol')
-        raise InvalidParameterError.new('protocol_id name', 'not starting with "admin"') if name.start_with?('admin')
-        raise InvalidParameterError.new('protocol_id name', 'not starting with "p "') if name.start_with?('p ')
-      end
-
-      # Key ID: 1-800 bytes
-      def validate_key_id!(key_id)
-        raise InvalidParameterError.new('key_id', 'a String') unless key_id.is_a?(String)
-
-        byte_length = key_id.bytesize
-        raise InvalidParameterError.new('key_id', 'between 1 and 800 bytes') if byte_length < 1 || byte_length > 800
-      end
-
-      # Counterparty: 'self', 'anyone', or 66-char hex (compressed pubkey)
-      def validate_counterparty!(counterparty)
-        return if %w[self anyone].include?(counterparty)
-
-        validate_pub_key_hex!(counterparty, 'counterparty')
-      end
-
-      # Description: 5-50 characters
-      def validate_description!(description, name = 'description')
-        raise InvalidParameterError.new(name, 'a String') unless description.is_a?(String)
-        raise InvalidParameterError.new(name, 'between 5 and 50 characters') if description.length < 5 || description.length > 50
-      end
-
-      # Basket name rules (BRC-99):
-      # - 5-300 chars
-      # - lowercase letters, numbers, and spaces only
-      # - no consecutive spaces
-      # - must not end with ' basket'
-      # - must not start with 'admin'
-      # - must not be 'default'
-      # - must not start with 'p ' (BRC-99 reserved)
-      def validate_basket!(basket)
-        raise InvalidParameterError.new('basket', 'a String') unless basket.is_a?(String)
-        raise InvalidParameterError.new('basket', 'between 5 and 300 characters') if basket.length < 5 || basket.length > 300
-        raise InvalidParameterError.new('basket', 'lowercase letters, numbers, and spaces only') unless basket.match?(/\A[a-z0-9 ]+\z/)
-        raise InvalidParameterError.new('basket', 'free of consecutive spaces') if basket.include?('  ')
-        raise InvalidParameterError.new('basket', 'not ending with " basket"') if basket.end_with?(' basket')
-        raise InvalidParameterError.new('basket', 'not starting with "admin"') if basket.start_with?('admin')
-        raise InvalidParameterError.new('basket', 'not equal to "default"') if basket == 'default'
-        raise InvalidParameterError.new('basket', 'not starting with "p "') if basket.start_with?('p ')
-      end
-
-      # Label: 1-300 characters
-      def validate_label!(label)
-        raise InvalidParameterError.new('label', 'a String') unless label.is_a?(String)
-        raise InvalidParameterError.new('label', 'between 1 and 300 characters') if label.empty? || label.length > 300
-      end
-
-      # Tag: 1-300 characters
-      def validate_tag!(tag)
-        raise InvalidParameterError.new('tag', 'a String') unless tag.is_a?(String)
-        raise InvalidParameterError.new('tag', 'between 1 and 300 characters') if tag.empty? || tag.length > 300
-      end
-
-      # Outpoint: "<64-hex-txid>.<non-negative-integer>"
-      def validate_outpoint!(outpoint)
-        raise InvalidParameterError.new('outpoint', 'a String') unless outpoint.is_a?(String)
-
-        parts = outpoint.split('.')
-        raise InvalidParameterError.new('outpoint', 'in format "<txid>.<index>"') unless parts.length == 2
-
-        txid, index = parts
-        raise InvalidParameterError.new('outpoint txid', 'a 64-character hex string') unless txid.match?(/\A[0-9a-f]{64}\z/)
-        raise InvalidParameterError.new('outpoint index', 'a non-negative integer') unless index.match?(/\A\d+\z/)
-      end
-
-      # Satoshis: 1 to 2_100_000_000_000_000
-      def validate_satoshis!(value, name = 'satoshis')
-        raise InvalidParameterError.new(name, 'an Integer') unless value.is_a?(Integer)
-        raise InvalidParameterError.new(name, 'between 1 and 2100000000000000') if value < 1 || value > 2_100_000_000_000_000
-      end
-
-      # Compressed public key hex: exactly 66 hex characters
-      def validate_pub_key_hex!(value, name = 'public_key')
-        raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
-        raise InvalidParameterError.new(name, 'a 66-character hex string (compressed public key)') unless value.match?(/\A[0-9a-f]{66}\z/)
-      end
-
-      # Hex string: even-length hex characters only
-      def validate_hex_string!(value, name = 'hex_string')
-        raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
-        raise InvalidParameterError.new(name, 'a valid hex string') unless value.match?(/\A[0-9a-f]*\z/) && value.length.even?
-      end
-
-      # Integer within bounds
-      def validate_integer!(value, name, min: nil, max: nil)
-        raise InvalidParameterError.new(name, 'an Integer') unless value.is_a?(Integer)
-        raise InvalidParameterError.new(name, "at least #{min}") if min && value < min
-        raise InvalidParameterError.new(name, "at most #{max}") if max && value > max
-      end
-    end
-  end
-end

data/lib/bsv/wallet_interface/version.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module WalletInterface
-    VERSION = '0.3.0'
-  end
-end