bsv-sdk 0.15.0 → 0.17.0

data/lib/bsv/wallet/proto_wallet.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require_relative 'proto_wallet/validators'
+require_relative 'proto_wallet/key_deriver'
+
+module BSV
+  module Wallet
+    # Minimal cryptographic wallet implementing the BRC-100 interface.
+    #
+    # ProtoWallet provides signing, encryption, HMAC, and key derivation
+    # without transactions, storage, or blockchain interaction. It is the
+    # direct implementation of the BRC-100 crypto methods, not a delegating
+    # client. This makes it suitable for use in the SDK's Auth module without
+    # depending on the bsv-wallet gem.
+    #
+    # Includes +BSV::Wallet::Interface::BRC100+ — methods it supports are
+    # overridden; unsupported methods (transactions, blockchain, authentication)
+    # fall through to +NotImplementedError+.
+    #
+    class ProtoWallet
+      include Interface::BRC100
+
+      # @param root_key [BSV::Primitives::PrivateKey, String] a private key or 'anyone'
+      def initialize(root_key)
+        @key_deriver = KeyDeriver.new(root_key)
+      end
+
+      # Returns a derived or identity public key.
+      #
+      # @param identity_key [Boolean] return the root identity key
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @param for_self [Boolean] derive from own identity
+      # @return [Hash] { public_key: String } hex-encoded compressed public key
+      def get_public_key(identity_key: false, protocol_id: nil, key_id: nil,
+                         counterparty: nil, for_self: false,
+                         privileged: false, privileged_reason: nil,
+                         seek_permission: true, originator: nil)
+        if identity_key
+          { public_key: @key_deriver.identity_key }
+        else
+          counterparty ||= 'self'
+          pub = @key_deriver.derive_public_key(
+            protocol_id, key_id, counterparty, for_self: for_self
+          )
+          { public_key: pub.to_hex }
+        end
+      end
+
+      # Encrypts plaintext using AES-256-GCM with a derived symmetric key.
+      #
+      # @param plaintext [Array<Integer>] byte array to encrypt
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @return [Hash] { ciphertext: Array<Integer> }
+      def encrypt(plaintext:, protocol_id:, key_id:,
+                  counterparty: nil, privileged: false, privileged_reason: nil,
+                  seek_permission: true, originator: nil)
+        sym_key    = derive_sym_key(protocol_id, key_id, counterparty)
+        ciphertext = sym_key.encrypt(bytes_to_string(plaintext))
+        { ciphertext: string_to_bytes(ciphertext) }
+      end
+
+      # Decrypts ciphertext using AES-256-GCM with a derived symmetric key.
+      #
+      # @param ciphertext [Array<Integer>] byte array to decrypt
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @return [Hash] { plaintext: Array<Integer> }
+      def decrypt(ciphertext:, protocol_id:, key_id:,
+                  counterparty: nil, privileged: false, privileged_reason: nil,
+                  seek_permission: true, originator: nil)
+        sym_key   = derive_sym_key(protocol_id, key_id, counterparty)
+        plaintext = sym_key.decrypt(bytes_to_string(ciphertext))
+        { plaintext: string_to_bytes(plaintext) }
+      end
+
+      # Creates an HMAC-SHA256 using a derived symmetric key.
+      #
+      # @param data [Array<Integer>] byte array to authenticate
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @return [Hash] { hmac: Array<Integer> }
+      def create_hmac(data:, protocol_id:, key_id:,
+                      counterparty: nil, privileged: false, privileged_reason: nil,
+                      seek_permission: true, originator: nil)
+        sym_key = derive_sym_key(protocol_id, key_id, counterparty)
+        hmac    = BSV::Primitives::Digest.hmac_sha256(sym_key.to_bytes, bytes_to_string(data))
+        { hmac: string_to_bytes(hmac) }
+      end
+
+      # Verifies an HMAC-SHA256 using a derived symmetric key.
+      #
+      # @param data [Array<Integer>] byte array that was authenticated
+      # @param hmac [Array<Integer>] HMAC to verify
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @return [Hash] { valid: true }
+      # @raise [InvalidHmacError] if the HMAC does not match
+      def verify_hmac(data:, hmac:, protocol_id:, key_id:,
+                      counterparty: nil, privileged: false, privileged_reason: nil,
+                      seek_permission: true, originator: nil)
+        sym_key  = derive_sym_key(protocol_id, key_id, counterparty)
+        expected = BSV::Primitives::Digest.hmac_sha256(sym_key.to_bytes, bytes_to_string(data))
+        provided = bytes_to_string(hmac)
+
+        raise InvalidHmacError unless secure_compare(expected, provided)
+
+        { valid: true }
+      end
+
+      # Creates an ECDSA signature using a derived private key.
+      #
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param data [Array<Integer>] data to hash and sign
+      # @param hash_to_directly_sign [Array<Integer>] pre-computed 32-byte hash
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @return [Hash] { signature: Array<Integer> } DER-encoded signature as byte array
+      def create_signature(protocol_id:, key_id:, data: nil, hash_to_directly_sign: nil,
+                           counterparty: nil, privileged: false, privileged_reason: nil,
+                           seek_permission: true, originator: nil)
+        counterparty ||= 'anyone'
+        BSV.logger&.debug { "[ProtoWallet] create_signature: protocol=#{protocol_id} key_id=#{key_id.inspect} counterparty=#{counterparty}" }
+        priv_key = @key_deriver.derive_private_key(protocol_id, key_id, counterparty)
+
+        hash = if hash_to_directly_sign
+                 bytes_to_string(hash_to_directly_sign)
+               else
+                 BSV::Primitives::Digest.sha256(bytes_to_string(data))
+               end
+
+        sig = priv_key.sign(hash)
+        { signature: string_to_bytes(sig.to_der) }
+      end
+
+      # Verifies an ECDSA signature using a derived public key.
+      #
+      # @param signature [Array<Integer>] DER-encoded signature as byte array
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @param data [Array<Integer>] original data that was signed
+      # @param hash_to_directly_verify [Array<Integer>] pre-computed 32-byte hash
+      # @param counterparty [String] pubkey hex, 'self', or 'anyone'
+      # @param for_self [Boolean] verify own derived key (default false)
+      # @return [Hash] { valid: true }
+      # @raise [InvalidSignatureError] if the signature does not verify
+      def verify_signature(signature:, protocol_id:, key_id:, data: nil,
+                           hash_to_directly_verify: nil,
+                           counterparty: nil, for_self: false,
+                           privileged: false, privileged_reason: nil,
+                           seek_permission: true, originator: nil)
+        counterparty ||= 'self'
+        BSV.logger&.debug do
+          "[ProtoWallet] verify_signature: protocol=#{protocol_id} key_id=#{key_id.inspect} " \
+            "counterparty=#{counterparty} for_self=#{for_self}"
+        end
+
+        pub_key = @key_deriver.derive_public_key(
+          protocol_id, key_id, counterparty, for_self: for_self
+        )
+
+        hash = if hash_to_directly_verify
+                 bytes_to_string(hash_to_directly_verify)
+               else
+                 BSV::Primitives::Digest.sha256(bytes_to_string(data))
+               end
+
+        sig   = BSV::Primitives::Signature.from_der(bytes_to_string(signature))
+        valid = pub_key.verify(hash, sig)
+        BSV.logger&.debug { "[ProtoWallet] verify_signature result=#{valid}" }
+
+        raise InvalidSignatureError unless valid
+
+        { valid: true }
+      end
+
+      # Reveals counterparty key linkage to a verifier (BRC-69 Method 1).
+      #
+      # @param counterparty [String] counterparty public key hex (not 'self' or 'anyone')
+      # @param verifier [String] verifier public key hex
+      # @return [Hash] { prover:, verifier:, counterparty:, revelation_time:,
+      #   encrypted_linkage:, encrypted_linkage_proof: }
+      def reveal_counterparty_key_linkage(counterparty:, verifier:,
+                                          privileged: false, privileged_reason: nil,
+                                          originator: nil)
+        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).
+      #
+      # @param counterparty [String] counterparty public key hex
+      # @param verifier [String] verifier public key hex
+      # @param protocol_id [Array] [security_level, protocol_name]
+      # @param key_id [String] key identifier
+      # @return [Hash] { prover:, verifier:, counterparty:, protocol_id:, key_id:,
+      #   encrypted_linkage:, encrypted_linkage_proof:, proof_type: }
+      def reveal_specific_key_linkage(counterparty:, verifier:, protocol_id:, key_id:,
+                                      privileged: false, privileged_reason: nil,
+                                      originator: nil)
+        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
+
+      # Returns an empty certificate list.
+      #
+      # ProtoWallet has no storage, so there are never any certificates.
+      #
+      # @return [Hash] { certificates: [] }
+      def list_certificates(certifiers: nil, types: nil, limit: 10, offset: 0,
+                            privileged: false, privileged_reason: nil, originator: nil)
+        { certificates: [] }
+      end
+
+      # Not supported — ProtoWallet has no certificate storage.
+      #
+      # @raise [UnsupportedActionError] always
+      def prove_certificate(certificate: nil, fields_to_reveal: nil, verifier: nil,
+                            privileged: false, privileged_reason: nil, originator: nil)
+        raise UnsupportedActionError, 'prove_certificate'
+      end
+
+      private
+
+      def derive_sym_key(protocol_id, key_id, counterparty)
+        counterparty ||= 'self'
+        @key_deriver.derive_symmetric_key(protocol_id, key_id, counterparty)
+      end
+
+      def bytes_to_string(bytes)
+        bytes.pack('C*')
+      end
+
+      def string_to_bytes(str)
+        str.unpack('C*')
+      end
+
+      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.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Shared contract: BRC-100 error classes and interface definition.
+    # These are the canonical definitions consumed by both bsv-sdk (ProtoWallet)
+    # and bsv-wallet (Engine).
+    require_relative 'wallet/errors'
+    require_relative 'wallet/interface'
+
+    # ProtoWallet — minimal crypto-only BRC-100 implementation.
+    # Its internals (KeyDeriver, Validators) are scoped under ProtoWallet::
+    # to avoid collision with bsv-wallet's own KeyDeriver.
+    require_relative 'wallet/proto_wallet'
+  end
+end

data/lib/bsv-sdk.rb

@@ -3,6 +3,20 @@
 require_relative 'bsv/version'
 
 module BSV
+  class << self
+    # Optional logger for debug-level instrumentation of txid conversions,
+    # BEEF wiring, and merkle path operations.
+    #
+    # No logger is configured by default — zero overhead when unused.
+    # Consumers opt in via:
+    #
+    #   require 'logger'
+    #   BSV.logger = Logger.new($stdout).tap { |l| l.level = Logger::DEBUG }
+    #
+    # @return [Logger, nil]
+    attr_accessor :logger
+  end
+
   autoload :Primitives,  'bsv/primitives'
   autoload :Script,      'bsv/script'
   autoload :Transaction, 'bsv/transaction'
@@ -13,5 +27,8 @@ module BSV
   autoload :Registry,    'bsv/registry'
   autoload :MCP,         'bsv/mcp'
 
-  autoload :WireFormat,  'bsv/wire_format'
+  # Wallet is loaded eagerly to avoid load-path shadowing when bsv-wallet is
+  # also in the bundle (bsv-wallet/lib/bsv/wallet.rb would otherwise win).
+  require_relative 'bsv/wallet'
+  autoload :WireFormat, 'bsv/wire_format'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -177,6 +191,13 @@ files:
 - lib/bsv/transaction/var_int.rb
 - lib/bsv/transaction/verification_error.rb
 - lib/bsv/version.rb
+- lib/bsv/wallet.rb
+- lib/bsv/wallet/errors.rb
+- lib/bsv/wallet/interface.rb
+- lib/bsv/wallet/interface/brc100.rb
+- lib/bsv/wallet/proto_wallet.rb
+- lib/bsv/wallet/proto_wallet/key_deriver.rb
+- lib/bsv/wallet/proto_wallet/validators.rb
 - lib/bsv/wire_format.rb
 homepage: https://github.com/sgbett/bsv-ruby-sdk
 licenses: