bsv-sdk 0.1.0

data/lib/bsv/primitives/ecdsa.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # Deterministic ECDSA signing and verification on secp256k1.
+    #
+    # Implements RFC 6979 deterministic nonce generation to produce
+    # signatures that are fully reproducible from the same (key, hash)
+    # pair. All signatures are normalised to low-S form (BIP-62 rule 5).
+    #
+    # Typically used indirectly via {PrivateKey#sign} and {PublicKey#verify}
+    # rather than calling this module directly.
+    module ECDSA
+      # Byte length of a secp256k1 scalar (256 bits).
+      BYTE_LEN = 32 # secp256k1 order is 256 bits = 32 bytes
+
+      module_function
+
+      # Sign a 32-byte message hash with a private key.
+      #
+      # @param hash [String] 32-byte message digest
+      # @param private_key_bn [OpenSSL::BN] the private key scalar
+      # @return [Signature] a low-S normalised signature
+      def sign(hash, private_key_bn)
+        sig, _recovery_id = sign_raw(hash, private_key_bn)
+        sig
+      end
+
+      # Sign a hash and return both the signature and recovery ID.
+      #
+      # The recovery ID (0-3) allows the public key to be recovered
+      # from the signature without knowing it in advance, as used by
+      # Bitcoin Signed Messages (BSM) and compact signature formats.
+      #
+      # @param hash [String] 32-byte message digest
+      # @param private_key_bn [OpenSSL::BN] the private key scalar
+      # @return [Array(Signature, Integer)] the signature and recovery ID
+      def sign_recoverable(hash, private_key_bn)
+        sign_raw(hash, private_key_bn)
+      end
+
+      # Recover a public key from a signature and recovery ID.
+      #
+      # Given a message hash, signature, and the recovery ID produced
+      # during signing, reconstructs the public key that created the
+      # signature.
+      #
+      # @param hash [String] 32-byte message digest that was signed
+      # @param signature [Signature] the ECDSA signature
+      # @param recovery_id [Integer] recovery ID (0-3)
+      # @return [PublicKey] the recovered public key
+      # @raise [ArgumentError] if the recovered point is at infinity
+      def recover_public_key(hash, signature, recovery_id)
+        r = signature.r
+        s = signature.s
+        n = Curve::N
+
+        # Reconstruct R.x (may include overflow when recovery_id >= 2)
+        x = recovery_id >= 2 ? r + n : r
+
+        # Decompress R from x-coordinate and y-parity
+        prefix = (recovery_id & 1).odd? ? "\x03".b : "\x02".b
+        x_bytes = x.to_s(2)
+        x_bytes = ("\x00".b * (32 - x_bytes.length)) + x_bytes if x_bytes.length < 32
+        r_point = Curve.point_from_bytes(prefix + x_bytes)
+
+        # Q = r^(-1) * (s*R - e*G)
+        r_inv = r.mod_inverse(n)
+        e = OpenSSL::BN.new(hash, 2)
+        u1 = ((n - e) * r_inv) % n
+        u2 = (s * r_inv) % n
+
+        p1 = Curve.multiply_generator(u1)
+        p2 = Curve.multiply_point(r_point, u2)
+        q = Curve.add_points(p1, p2)
+
+        raise ArgumentError, 'recovered point is at infinity' if q.infinity?
+
+        PublicKey.new(q)
+      end
+
+      # Verify an ECDSA signature against a message hash and public key.
+      #
+      # @param hash [String] 32-byte message digest
+      # @param signature [Signature] the signature to verify
+      # @param public_key_point [OpenSSL::PKey::EC::Point] the signer's public key point
+      # @return [Boolean] +true+ if the signature is valid
+      def verify(hash, signature, public_key_point)
+        r = signature.r
+        s = signature.s
+        n = Curve::N
+
+        return false if r <= OpenSSL::BN.new('0') || r >= n
+        return false if s <= OpenSSL::BN.new('0') || s >= n
+
+        e = OpenSSL::BN.new(hash, 2)
+        s_inv = s.mod_inverse(n)
+
+        u1 = (e * s_inv) % n
+        u2 = (r * s_inv) % n
+
+        # R' = u1*G + u2*Q
+        point1 = Curve.multiply_generator(u1)
+        point2 = Curve.multiply_point(public_key_point, u2)
+        result_point = Curve.add_points(point1, point2)
+
+        return false if result_point.infinity?
+
+        x = Curve.point_x(result_point) % n
+        x == r
+      end
+
+      class << self
+        private
+
+        def sign_raw(hash, private_key_bn)
+          k = nonce_rfc6979(private_key_bn, hash)
+          k_inv = k.mod_inverse(Curve::N)
+
+          r_point = Curve.multiply_generator(k)
+          r = Curve.point_x(r_point) % Curve::N
+          raise 'calculated R is zero' if r.zero?
+
+          e = OpenSSL::BN.new(hash, 2)
+          s = (k_inv * ((e + (private_key_bn * r)) % Curve::N)) % Curve::N
+          raise 'calculated S is zero' if s.zero?
+
+          # Recovery ID: bit 0 = R.y parity, bit 1 = R.x overflow (>= N)
+          r_y_odd = r_point.to_octet_string(:compressed).getbyte(0) == 0x03
+          r_overflow = Curve.point_x(r_point) >= Curve::N
+          recovery_id = (r_y_odd ? 1 : 0) + (r_overflow ? 2 : 0)
+
+          sig = Signature.new(r, s)
+          unless sig.low_s?
+            sig = sig.to_low_s
+            recovery_id ^= 1 # Flipping s negates R.y, toggling parity
+          end
+
+          [sig, recovery_id]
+        end
+
+        # RFC 6979 Section 3.2 — deterministic k generation for secp256k1/SHA-256
+        def nonce_rfc6979(privkey_bn, hash)
+          q = Curve::N
+          qlen = q.num_bits # 256 for secp256k1
+          rolen = (qlen + 7) >> 3 # 32
+
+          # a. Process input: private key as fixed-width octets
+          x_bytes = int2octets(privkey_bn, rolen)
+          # b. Process hash
+          h_bytes = bits2octets(hash, rolen)
+
+          # bx = int2octets(x) || bits2octets(hash)
+          bx = x_bytes + h_bytes
+
+          # Step B: V = 0x01 * hlen (32 bytes of 0x01)
+          v = "\x01".b * 32
+
+          # Step C: K = 0x00 * hlen (32 bytes of 0x00)
+          k = "\x00".b * 32
+
+          # Step D: K = HMAC(K, V || 0x00 || bx)
+          k = Digest.hmac_sha256(k, v + "\x00".b + bx)
+
+          # Step E: V = HMAC(K, V)
+          v = Digest.hmac_sha256(k, v)
+
+          # Step F: K = HMAC(K, V || 0x01 || bx)
+          k = Digest.hmac_sha256(k, v + "\x01".b + bx)
+
+          # Step G: V = HMAC(K, V)
+          v = Digest.hmac_sha256(k, v)
+
+          # Step H: Generate and test candidates
+          loop do
+            # H1/H2: Generate qlen bits
+            t = ''.b
+            while t.length * 8 < qlen
+              v = Digest.hmac_sha256(k, v)
+              t += v
+            end
+
+            # H3: Convert to integer and test
+            secret = bits2int(t, qlen)
+            return secret if secret >= OpenSSL::BN.new('1') && secret < q
+
+            # Not valid — update K, V and retry
+            k = Digest.hmac_sha256(k, v + "\x00".b)
+            v = Digest.hmac_sha256(k, v)
+          end
+        end
+
+        # Convert integer to fixed-width big-endian octets
+        def int2octets(bn, rolen)
+          bytes = bn.to_s(2)
+          if bytes.length > rolen
+            bytes[-rolen, rolen]
+          elsif bytes.length < rolen
+            ("\x00".b * (rolen - bytes.length)) + bytes
+          else
+            bytes
+          end
+        end
+
+        # Convert hash bits to integer, reduce mod q, then to octets
+        def bits2octets(hash_bytes, rolen)
+          z1 = bits2int(hash_bytes, Curve::N.num_bits)
+          z2 = z1 % Curve::N
+          int2octets(z2, rolen)
+        end
+
+        # Convert bit string to integer, right-shifting if longer than qlen
+        def bits2int(bytes, qlen)
+          blen = bytes.length * 8
+          v = OpenSSL::BN.new(bytes, 2)
+          v >>= (blen - qlen) if blen > qlen
+          v
+        end
+      end
+    end
+  end
+end

data/lib/bsv/primitives/ecies.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # Elliptic Curve Integrated Encryption Scheme (ECIES) using the
+    # Electrum/BIE1 protocol.
+    #
+    # Provides authenticated encryption using an ephemeral ECDH shared secret.
+    # The sender generates a random key pair, derives a shared secret with the
+    # recipient's public key, then encrypts with AES-128-CBC and authenticates
+    # with HMAC-SHA-256 (encrypt-then-MAC).
+    #
+    # @example Encrypt and decrypt a message
+    #   alice = BSV::Primitives::PrivateKey.generate
+    #   bob   = BSV::Primitives::PrivateKey.generate
+    #
+    #   ciphertext = BSV::Primitives::ECIES.encrypt('hello', bob.public_key)
+    #   plaintext  = BSV::Primitives::ECIES.decrypt(ciphertext, bob)
+    module ECIES
+      # BIE1 magic bytes identifying the Electrum ECIES format.
+      MAGIC = 'BIE1'.b.freeze
+
+      # Raised when HMAC verification or AES decryption fails.
+      class DecryptionError < StandardError; end
+
+      module_function
+
+      # Encrypt a message for a recipient's public key.
+      #
+      # @param message [String] the plaintext message
+      # @param public_key [PublicKey] the recipient's public key
+      # @param private_key [PrivateKey, nil] optional ephemeral key (random if omitted)
+      # @return [String] encrypted payload: BIE1 magic + ephemeral pubkey + ciphertext + HMAC
+      def encrypt(message, public_key, private_key: nil)
+        message = message.b if message.encoding != Encoding::ASCII_8BIT
+
+        ephemeral = private_key || PrivateKey.generate
+        ephemeral_pub = ephemeral.public_key
+
+        iv, key_e, key_m = derive_keys(public_key.point, ephemeral.bn)
+
+        cipher = OpenSSL::Cipher.new('aes-128-cbc')
+        cipher.encrypt
+        cipher.key = key_e
+        cipher.iv = iv
+        ciphertext = message.empty? ? cipher.final : cipher.update(message) + cipher.final
+
+        payload = MAGIC + ephemeral_pub.compressed + ciphertext
+        mac = Digest.hmac_sha256(key_m, payload)
+
+        payload + mac
+      end
+
+      # Decrypt an ECIES-encrypted message with a private key.
+      #
+      # Verifies the HMAC before attempting decryption (encrypt-then-MAC).
+      #
+      # @param data [String] the encrypted payload (BIE1 format)
+      # @param private_key [PrivateKey] the recipient's private key
+      # @return [String] the decrypted plaintext
+      # @raise [ArgumentError] if the data is too short or has invalid magic bytes
+      # @raise [DecryptionError] if HMAC verification or AES decryption fails
+      def decrypt(data, private_key)
+        data = data.b if data.encoding != Encoding::ASCII_8BIT
+
+        raise ArgumentError, 'data too short' if data.bytesize < 85
+
+        magic = data[0, 4]
+        raise ArgumentError, 'invalid magic: expected BIE1' unless magic == MAGIC
+
+        ephemeral_pub_bytes = data[4, 33]
+        mac = data[-32, 32]
+        ciphertext = data[37...-32]
+
+        ephemeral_pub = PublicKey.from_bytes(ephemeral_pub_bytes)
+
+        iv, key_e, key_m = derive_keys(ephemeral_pub.point, private_key.bn)
+
+        # Verify HMAC before decryption (encrypt-then-MAC)
+        payload = data[0...-32]
+        expected_mac = Digest.hmac_sha256(key_m, payload)
+
+        raise DecryptionError, 'HMAC verification failed' unless secure_compare(mac, expected_mac)
+
+        begin
+          cipher = OpenSSL::Cipher.new('aes-128-cbc')
+          cipher.decrypt
+          cipher.key = key_e
+          cipher.iv = iv
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError => e
+          raise DecryptionError, "decryption failed: #{e.message}"
+        end
+      end
+
+      class << self
+        private
+
+        def secure_compare(mac, expected)
+          return false unless mac.bytesize == expected.bytesize
+
+          if OpenSSL.respond_to?(:fixed_length_secure_compare)
+            OpenSSL.fixed_length_secure_compare(mac, expected)
+          else
+            # Constant-time comparison for Ruby < 3.2
+            result = 0
+            mac.bytes.zip(expected.bytes) { |x, y| result |= x ^ y }
+            result.zero?
+          end
+        end
+
+        def derive_keys(point, scalar_bn)
+          shared_point = Curve.multiply_point(point, scalar_bn)
+          ecdh_key = shared_point.to_octet_string(:compressed)
+          derived = Digest.sha512(ecdh_key)
+
+          iv    = derived[0, 16]
+          key_e = derived[16, 16]
+          key_m = derived[32, 32]
+
+          [iv, key_e, key_m]
+        end
+      end
+    end
+  end
+end

data/lib/bsv/primitives/extended_key.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Primitives
+    # BIP-32 hierarchical deterministic (HD) extended key.
+    #
+    # Supports both private and public extended keys, serialised as
+    # Base58Check xprv/xpub strings. Provides child key derivation
+    # (normal and hardened), path-based derivation (+m/44'/0'/0'+),
+    # and neutering (private → public).
+    #
+    # @example Derive keys from a seed
+    #   seed = SecureRandom.random_bytes(32)
+    #   master = BSV::Primitives::ExtendedKey.from_seed(seed)
+    #   child  = master.derive_path("m/44'/0'/0'/0/0")
+    #   child.public_key.address #=> "1..."
+    #
+    # @example Parse an xpub string
+    #   xpub = BSV::Primitives::ExtendedKey.from_string('xpub6...')
+    #   xpub.public? #=> true
+    class ExtendedKey
+      # Offset added to child indices for hardened derivation.
+      HARDENED = 0x80000000
+
+      # Version bytes for extended key serialisation (BIP-32).
+      VERSIONS = {
+        mainnet_private: "\x04\x88\xAD\xE4".b,
+        mainnet_public: "\x04\x88\xB2\x1E".b,
+        testnet_private: "\x04\x35\x83\x94".b,
+        testnet_public: "\x04\x35\x87\xCF".b
+      }.freeze
+
+      # Private extended key version bytes.
+      PRIVATE_VERSIONS = [VERSIONS[:mainnet_private], VERSIONS[:testnet_private]].freeze
+
+      # Public extended key version bytes.
+      PUBLIC_VERSIONS  = [VERSIONS[:mainnet_public], VERSIONS[:testnet_public]].freeze
+
+      # @return [String] raw key bytes (32-byte private or 33-byte compressed public)
+      attr_reader :key
+
+      # @return [String] 32-byte chain code for child derivation
+      attr_reader :chain_code
+
+      # @return [Integer] depth in the derivation tree (0 = master)
+      attr_reader :depth
+
+      # @return [String] 4-byte fingerprint of the parent key
+      attr_reader :parent_fingerprint
+
+      # @return [Integer] child number (index used to derive this key)
+      attr_reader :child_number
+
+      # @return [String] 4-byte version prefix
+      attr_reader :version
+
+      # @param key [String] raw key bytes
+      # @param chain_code [String] 32-byte chain code
+      # @param version [String] 4-byte version prefix
+      # @param depth [Integer] derivation depth
+      # @param parent_fingerprint [String] 4-byte parent fingerprint
+      # @param child_number [Integer] child index
+      def initialize(key:, chain_code:, version:, depth: 0, parent_fingerprint: "\x00\x00\x00\x00".b,
+                     child_number: 0)
+        @key = key
+        @chain_code = chain_code
+        @depth = depth
+        @parent_fingerprint = parent_fingerprint
+        @child_number = child_number
+        @version = version
+      end
+
+      # Derive a master extended key from a binary seed.
+      #
+      # Uses HMAC-SHA-512 with key +"Bitcoin seed"+ per BIP-32.
+      #
+      # @param seed [String] 16-64 byte seed (typically from {Mnemonic#to_seed})
+      # @param network [Symbol] +:mainnet+ or +:testnet+
+      # @return [ExtendedKey] the master private extended key
+      # @raise [ArgumentError] if the seed length is invalid or derives an invalid key
+      def self.from_seed(seed, network: :mainnet)
+        seed = seed.b
+        raise ArgumentError, 'seed must be between 16 and 64 bytes' unless seed.length.between?(16, 64)
+
+        hmac = Digest.hmac_sha512('Bitcoin seed', seed)
+        il = hmac[0, 32]
+        ir = hmac[32, 32]
+
+        il_bn = OpenSSL::BN.new(il, 2)
+        raise ArgumentError, 'invalid seed: derived key is zero or >= curve order' if il_bn.zero? || il_bn >= Curve::N
+
+        new(
+          key: il,
+          chain_code: ir,
+          version: VERSIONS[:"#{network}_private"]
+        )
+      end
+
+      # Parse an extended key from a Base58Check-encoded string (xprv/xpub).
+      #
+      # @param base58 [String] Base58Check-encoded extended key
+      # @return [ExtendedKey]
+      # @raise [ArgumentError] if the encoding, length, or version/key mismatch is invalid
+      def self.from_string(base58)
+        data = Base58.check_decode(base58)
+        raise ArgumentError, "invalid extended key length: #{data.length}" unless data.length == 78
+
+        version = data[0, 4]
+        depth = data[4].unpack1('C')
+        parent_fingerprint = data[5, 4]
+        child_number = data[9, 4].unpack1('N')
+        chain_code = data[13, 32]
+        key_data = data[45, 33]
+
+        if key_data[0] == "\x00".b
+          raise ArgumentError, 'private key data with public version bytes' unless PRIVATE_VERSIONS.include?(version)
+
+          key = key_data[1, 32]
+        elsif ["\x02".b, "\x03".b].include?(key_data[0])
+          raise ArgumentError, 'public key data with private version bytes' unless PUBLIC_VERSIONS.include?(version)
+
+          key = key_data
+        else
+          raise ArgumentError, "invalid key data prefix: 0x#{key_data[0].unpack1('H*')}"
+        end
+
+        new(
+          key: key,
+          chain_code: chain_code,
+          version: version,
+          depth: depth,
+          parent_fingerprint: parent_fingerprint,
+          child_number: child_number
+        )
+      end
+
+      # Whether this is a private extended key.
+      #
+      # @return [Boolean]
+      def private?
+        PRIVATE_VERSIONS.include?(@version)
+      end
+
+      # Whether this is a public extended key.
+      #
+      # @return [Boolean]
+      def public?
+        PUBLIC_VERSIONS.include?(@version)
+      end
+
+      # Derive a child key at the given index.
+      #
+      # Indices below {HARDENED} produce normal (public-derivable) children.
+      # Indices >= {HARDENED} produce hardened children (private key required).
+      #
+      # @param index [Integer] the child index (use +HARDENED + n+ for hardened)
+      # @return [ExtendedKey] the derived child key
+      # @raise [ArgumentError] if deriving hardened from a public key, or at max depth
+      def child(index)
+        raise ArgumentError, 'cannot derive child at depth 255' if @depth >= 255
+
+        if index >= HARDENED
+          raise ArgumentError, 'cannot derive hardened child from public key' if public?
+
+          data = "\x00".b + padded_key + [index].pack('N')
+        else
+          data = compressed_pubkey_bytes + [index].pack('N')
+        end
+
+        hmac = Digest.hmac_sha512(@chain_code, data)
+        il = hmac[0, 32]
+        ir = hmac[32, 32]
+
+        il_bn = OpenSSL::BN.new(il, 2)
+        raise ArgumentError, 'invalid child: IL >= curve order' if il_bn >= Curve::N
+
+        fp = fingerprint
+
+        child_key_bytes = if private?
+                            child_key_bn = il_bn.mod_add(OpenSSL::BN.new(@key, 2), Curve::N)
+                            raise ArgumentError, 'invalid child: derived key is zero' if child_key_bn.zero?
+
+                            bn_to_32bytes(child_key_bn)
+                          else
+                            parent_point = Curve.point_from_bytes(@key)
+                            il_point = Curve.multiply_generator(il_bn)
+                            child_point = Curve.add_points(parent_point, il_point)
+                            raise ArgumentError, 'invalid child: derived point is at infinity' if child_point.infinity?
+
+                            child_point.to_octet_string(:compressed)
+                          end
+
+        self.class.new(
+          key: child_key_bytes,
+          chain_code: ir,
+          version: @version,
+          depth: @depth + 1,
+          parent_fingerprint: fp,
+          child_number: index
+        )
+      end
+
+      # Derive a child key from a BIP-32 path string.
+      #
+      # @param path [String] derivation path (e.g. +"m/44'/0'/0'/0/0"+)
+      # @return [ExtendedKey] the derived key
+      # @raise [ArgumentError] if the path does not start with +'m'+
+      def derive_path(path)
+        components = path.strip.split('/')
+        raise ArgumentError, "path must start with 'm'" unless components.first == 'm'
+
+        components[1..].reduce(self) do |key, component|
+          hardened = component.end_with?("'", 'H', 'h')
+          index = component.to_i
+          index += HARDENED if hardened
+          key.child(index)
+        end
+      end
+
+      # Convert a private extended key to its public counterpart.
+      #
+      # @return [ExtendedKey] the public extended key (xpub)
+      # @raise [ArgumentError] if already a public key
+      def neuter
+        raise ArgumentError, 'already a public key' if public?
+
+        pub_version = if @version == VERSIONS[:mainnet_private]
+                        VERSIONS[:mainnet_public]
+                      else
+                        VERSIONS[:testnet_public]
+                      end
+
+        self.class.new(
+          key: compressed_pubkey_bytes,
+          chain_code: @chain_code,
+          version: pub_version,
+          depth: @depth,
+          parent_fingerprint: @parent_fingerprint,
+          child_number: @child_number
+        )
+      end
+
+      # Serialise as a Base58Check-encoded string (xprv or xpub).
+      #
+      # @return [String] the Base58Check-encoded extended key
+      def to_s
+        key_data = private? ? "\x00".b + padded_key : @key
+
+        payload = @version +
+                  [@depth].pack('C') +
+                  @parent_fingerprint +
+                  [@child_number].pack('N') +
+                  @chain_code +
+                  key_data
+
+        Base58.check_encode(payload)
+      end
+
+      # Extract the {PrivateKey} from a private extended key.
+      #
+      # @return [PrivateKey]
+      # @raise [ArgumentError] if this is a public extended key
+      def private_key
+        raise ArgumentError, 'not a private extended key' unless private?
+
+        PrivateKey.from_bytes(padded_key)
+      end
+
+      # Extract the {PublicKey} from this extended key.
+      #
+      # @return [PublicKey]
+      def public_key
+        PublicKey.from_bytes(compressed_pubkey_bytes)
+      end
+
+      # The 4-byte fingerprint of this key (first 4 bytes of identifier).
+      #
+      # @return [String] 4-byte fingerprint
+      def fingerprint
+        identifier[0, 4]
+      end
+
+      # The 20-byte Hash160 identifier for this key.
+      #
+      # @return [String] 20-byte Hash160 of the compressed public key
+      def identifier
+        Digest.hash160(compressed_pubkey_bytes)
+      end
+
+      private
+
+      def compressed_pubkey_bytes
+        if private?
+          bn = OpenSSL::BN.new(@key, 2)
+          point = Curve.multiply_generator(bn)
+          point.to_octet_string(:compressed)
+        else
+          @key
+        end
+      end
+
+      def padded_key
+        raw = @key.b
+        raw.length < 32 ? ("\x00".b * (32 - raw.length)) + raw : raw
+      end
+
+      def bn_to_32bytes(bn)
+        raw = bn.to_s(2)
+        raw.length < 32 ? ("\x00".b * (32 - raw.length)) + raw : raw
+      end
+    end
+  end
+end