bsv-sdk 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b45240189e3a6531b7273ee4df823490c1f892ae332257743b74783f2e88ef87
-  data.tar.gz: b3ffa3feb075fb232b87a50149af07139ef01d1d80edb03c7e595f758fe01a84
+  metadata.gz: 9924711798c6f50752254b528fb1956bcc39e3cf5cf1b57fdf94a887a3dc9688
+  data.tar.gz: d3cd183e1ccdafadbe37b989275cd03d4c505e2432b3ede6d1af5213b7455361
 SHA512:
-  metadata.gz: 28cb3358d0483ad4574e1ef3a57c6f85f45e4404de0a70faea6e8b431b9c47655b490e73f4779ca74a617e35bcdadd65eb7f5e2cbd9310199a3af494af4a9187
-  data.tar.gz: 5a4f40bf35ba4dc93a260c6729871a165ebb4e468b802f664371bcf0574d3aacf23d91f8ca9634a739af6cd4443e8b264b9256a2888ddfd725289f98a606b3a9
+  metadata.gz: 88f3ed7869e81aec560b47a405e9144d00e3e48cf4b62d5be6bd09e58ac216ebbe8b56ebcff2ac61075c901d56308875b7ff4673d2e066df74f723e6391f3ea5
+  data.tar.gz: a88d52282aa5d2a05b906685245b6690c434dbea73fb01ed99be1dc93a4706720c13ee5fb48830a4c3c423c9160db264fe66c910de5995c94047f61e7f56120d

data/lib/bsv/auth/auth_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module BSV
+  module Auth
+    # Raised when a BRC-31 authentication protocol error occurs.
+    class AuthError < StandardError; end
+  end
+end

data/lib/bsv/auth/nonce.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'securerandom'
+
+module BSV
+  module Auth
+    # Nonce creation and verification for BRC-31 mutual authentication.
+    #
+    # A nonce is a 48-byte value: 16 random bytes concatenated with a 32-byte
+    # HMAC-SHA256 over those 16 bytes, base64-encoded. The HMAC is computed
+    # with the wallet using protocol [2, 'server hmac'] and the raw bytes as
+    # the key ID (decoded to a string). This makes nonces self-authenticating —
+    # only the wallet that created a nonce can verify it.
+    #
+    # The key ID is derived by decoding the 16 random bytes as UTF-8, replacing
+    # any invalid byte sequences with the Unicode replacement character (U+FFFD).
+    # This matches the ts-sdk behaviour (TextDecoder in non-fatal replacement mode).
+    # Since nonces are always self-verified (counterparty='self'), the key ID
+    # encoding does not need to be interoperable across SDK implementations.
+    module Nonce
+      PROTOCOL_ID  = [2, 'server hmac'].freeze
+      RANDOM_BYTES = 16
+
+      module_function
+
+      # Creates a self-authenticating nonce.
+      #
+      # @param wallet [BSV::Wallet::Interface] wallet with HMAC capability
+      # @param counterparty [String] counterparty ('self', 'anyone', or public key hex).
+      #   Defaults to 'self' — nonces are self-verified by the creating wallet.
+      # @return [String] base64-encoded nonce (48 bytes: 16 random + 32 HMAC)
+      def create(wallet, counterparty = 'self')
+        first_half = SecureRandom.random_bytes(RANDOM_BYTES)
+        key_id     = decode_as_utf8(first_half)
+
+        result = wallet.create_hmac({
+                                      data: first_half.bytes,
+                                      protocol_id: PROTOCOL_ID,
+                                      key_id: key_id,
+                                      counterparty: counterparty
+                                    })
+
+        nonce_bytes = first_half + result[:hmac].pack('C*')
+        ::Base64.strict_encode64(nonce_bytes)
+      end
+
+      # Verifies that a nonce was created by the given wallet.
+      #
+      # @param nonce [String] base64-encoded nonce to verify
+      # @param wallet [BSV::Wallet::Interface] wallet
+      # @param counterparty [String] counterparty — must match the value used
+      #   when the nonce was created (typically 'self')
+      # @return [Boolean] true if the nonce is valid
+      def verify(nonce, wallet, counterparty = 'self')
+        nonce_bytes = ::Base64.strict_decode64(nonce)
+        return false if nonce_bytes.bytesize <= RANDOM_BYTES
+
+        first_half = nonce_bytes.byteslice(0, RANDOM_BYTES)
+        hmac_bytes = nonce_bytes.byteslice(RANDOM_BYTES, nonce_bytes.bytesize - RANDOM_BYTES)
+        key_id     = decode_as_utf8(first_half)
+
+        wallet.verify_hmac({
+                             data: first_half.bytes,
+                             hmac: hmac_bytes.bytes,
+                             protocol_id: PROTOCOL_ID,
+                             key_id: key_id,
+                             counterparty: counterparty
+                           })
+
+        true
+      rescue BSV::Wallet::InvalidHmacError
+        false
+      end
+
+      # Decodes a binary string as UTF-8, replacing invalid byte sequences with
+      # the Unicode replacement character (U+FFFD). Used to derive the HMAC key
+      # ID from the random nonce bytes in a way consistent with the ts-sdk's
+      # use of TextDecoder (non-fatal mode).
+      #
+      # @param bytes [String] binary (ASCII-8BIT) string
+      # @return [String] UTF-8 encoded string
+      def decode_as_utf8(bytes)
+        bytes.encode('UTF-8', 'binary', invalid: :replace, undef: :replace, replace: "\uFFFD")
+      end
+    end
+  end
+end

data/lib/bsv/auth/peer.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module BSV
+  module Auth
+    # BRC-31/BRC-103 mutual authentication peer.
+    #
+    # Manages the cryptographic handshake between two parties:
+    #
+    # 1. Alice calls {#initiate_handshake} — sends +initialRequest+ with her
+    #    session nonce and requested certificates.
+    # 2. Bob calls {#handle_incoming_message} — processes the request, creates
+    #    his own session nonce, signs +decode(alice_nonce) + decode(bob_nonce)+,
+    #    and sends +initialResponse+.
+    # 3. Alice processes +initialResponse+ — verifies the nonce is hers
+    #    (via HMAC), verifies Bob's signature, and marks the session authenticated.
+    # 4. Both parties may now exchange authenticated +general+ messages.
+    #
+    # Sessions are indexed by +session_nonce+ (our nonce), which is the primary
+    # key in the {SessionManager}.
+    #
+    # @example Using Peer with a custom transport
+    #   wallet_a = BSV::Wallet::ProtoWallet.new(BSV::Primitives::PrivateKey.generate)
+    #   wallet_b = BSV::Wallet::ProtoWallet.new(BSV::Primitives::PrivateKey.generate)
+    #
+    #   # Wire the two peers together with synchronous in-process transports
+    #   peer_a = BSV::Auth::Peer.new(wallet: wallet_a)
+    #   peer_b = BSV::Auth::Peer.new(wallet: wallet_b)
+    #
+    #   # Alice initiates; Bob responds; Alice completes
+    #   request  = peer_a.create_initial_request
+    #   response = peer_b.handle_incoming_message(request)
+    #   peer_a.handle_incoming_message(response)
+    class Peer
+      AUTH_PROTOCOL = [2, 'auth message signature'].freeze
+
+      attr_reader :wallet, :session_manager
+
+      # @param wallet [BSV::Wallet::Interface] wallet providing crypto operations
+      # @param transport [Transport, nil] optional transport for async usage
+      # @param session_manager [SessionManager, nil] optional custom session store
+      # @param certificates_to_request [Hash, nil] certificate set to request from peers
+      def initialize(wallet:, transport: nil, session_manager: nil, certificates_to_request: nil)
+        @wallet                  = wallet
+        @transport               = transport
+        @session_manager         = session_manager || SessionManager.new
+        @certificates_to_request = certificates_to_request || { certifiers: [], types: {} }
+        @identity_public_key     = nil
+
+        return unless @transport
+
+        @transport.on_data { |msg| handle_incoming_message(msg) }
+      end
+
+      # Returns our identity key (cached after first call).
+      #
+      # @return [String] compressed public key hex
+      def identity_key
+        @identity_key ||= @wallet.get_public_key({ identity_key: true })[:public_key]
+      end
+
+      # Checks whether we have an authenticated session with a peer.
+      #
+      # Accepts either a +session_nonce+ or +peer_identity_key+.
+      #
+      # @param identifier [String]
+      # @return [Boolean]
+      def authenticated?(identifier)
+        session = @session_manager.get_session(identifier)
+        session&.authenticated? || false
+      end
+
+      # --- Handshake initiation (we are the initiator) ---
+
+      # Builds an +initialRequest+ message and creates a pending session.
+      #
+      # @return [Hash] the message to send to the peer
+      def create_initial_request
+        session_nonce = Nonce.create(@wallet)
+
+        session = PeerSession.new(session_nonce: session_nonce)
+        session.certificates_required  = certifiers_present?
+        session.certificates_validated = !session.certificates_required
+
+        @session_manager.add_session(session)
+
+        {
+          version: AUTH_VERSION,
+          message_type: MSG_INITIAL_REQUEST,
+          identity_key: identity_key,
+          initial_nonce: session_nonce,
+          requested_certificates: @certificates_to_request
+        }
+      end
+
+      # --- Incoming message dispatch ---
+
+      # Processes any incoming auth message and returns a response (if applicable).
+      #
+      # @param message [Hash] the incoming auth message
+      # @return [Hash, nil] response message, or nil for messages requiring no reply
+      # @raise [AuthError] if the version is wrong or the message type is unknown
+      def handle_incoming_message(message)
+        version = message[:version] || message['version']
+        raise AuthError, "Unsupported auth version: #{version.inspect} (expected #{AUTH_VERSION})" unless version == AUTH_VERSION
+
+        type = message[:message_type] || message['message_type']
+
+        case type
+        when MSG_INITIAL_REQUEST  then process_initial_request(message)
+        when MSG_INITIAL_RESPONSE then process_initial_response(message)
+        when MSG_GENERAL          then process_general_message(message)
+        else
+          raise AuthError, "Unknown message type: #{type.inspect}"
+        end
+      end
+
+      # --- General message exchange (post-handshake) ---
+
+      # Creates an authenticated +general+ message to send to a peer.
+      #
+      # @param peer_identifier [String] peer's session nonce or identity key
+      # @param payload [Array<Integer>] byte array payload
+      # @return [Hash] the message to send
+      # @raise [AuthError] if not authenticated with this peer
+      def create_general_message(peer_identifier, payload)
+        session = @session_manager.get_session(peer_identifier)
+        raise AuthError, "Not authenticated with peer #{peer_identifier.inspect}" unless session&.authenticated?
+
+        # The receiver verifies `your_nonce` using their own wallet — so it must
+        # be the peer's nonce (the nonce THEY created during the handshake).
+        request_nonce = ::Base64.strict_encode64(SecureRandom.random_bytes(32))
+        key_id        = key_id_for(request_nonce, session.peer_nonce)
+
+        sig_result = @wallet.create_signature({
+                                                data: payload,
+                                                protocol_id: AUTH_PROTOCOL,
+                                                key_id: key_id,
+                                                counterparty: session.peer_identity_key
+                                              })
+
+        session.last_update = current_time_ms
+        @session_manager.update_session(session)
+
+        {
+          version: AUTH_VERSION,
+          message_type: MSG_GENERAL,
+          identity_key: identity_key,
+          nonce: request_nonce,
+          your_nonce: session.peer_nonce,
+          payload: payload,
+          signature: sig_result[:signature]
+        }
+      end
+
+      private
+
+      # --- Processing: initial request (we are the responder) ---
+
+      def process_initial_request(message)
+        peer_key        = fetch!(message, :identity_key)
+        their_nonce     = fetch!(message, :initial_nonce)
+
+        raise AuthError, 'initial_nonce must not be empty' if their_nonce.empty?
+
+        our_nonce = Nonce.create(@wallet)
+
+        session                        = PeerSession.new(session_nonce: our_nonce)
+        session.peer_identity_key      = peer_key
+        session.peer_nonce             = their_nonce
+        session.is_authenticated       = true
+        session.certificates_required  = certifiers_present?
+        session.certificates_validated = !session.certificates_required
+        session.last_update            = current_time_ms
+
+        @session_manager.add_session(session)
+
+        # Sign decode(their_nonce) + decode(our_nonce)
+        # Key ID: "their_nonce our_nonce"  (initiator_nonce responder_nonce)
+        sig_data = b64_decode(their_nonce) + b64_decode(our_nonce)
+        key_id   = key_id_for(their_nonce, our_nonce)
+
+        sig_result = @wallet.create_signature({
+                                                data: sig_data,
+                                                protocol_id: AUTH_PROTOCOL,
+                                                key_id: key_id,
+                                                counterparty: peer_key
+                                              })
+
+        {
+          version: AUTH_VERSION,
+          message_type: MSG_INITIAL_RESPONSE,
+          identity_key: identity_key,
+          initial_nonce: our_nonce,
+          your_nonce: their_nonce,
+          requested_certificates: @certificates_to_request,
+          signature: sig_result[:signature]
+        }
+      end
+
+      # --- Processing: initial response (we are the initiator) ---
+
+      def process_initial_response(message)
+        their_nonce = fetch!(message, :initial_nonce)  # responder's nonce
+        our_nonce   = fetch!(message, :your_nonce)     # our nonce echoed back
+        peer_key    = fetch!(message, :identity_key)
+        signature   = fetch!(message, :signature)
+
+        # Verify the echoed nonce is one we created
+        raise AuthError, "Nonce verification failed from peer: #{peer_key}" unless Nonce.verify(our_nonce, @wallet)
+
+        session = @session_manager.get_session(our_nonce)
+        raise AuthError, "No pending session for nonce: #{our_nonce.inspect}" unless session
+
+        # Verify responder's signature over decode(our_nonce) + decode(their_nonce)
+        # Key ID: "our_nonce their_nonce"  (initiator_nonce responder_nonce)
+        sig_data = b64_decode(our_nonce) + b64_decode(their_nonce)
+        key_id   = key_id_for(our_nonce, their_nonce)
+
+        @wallet.verify_signature({
+                                   data: sig_data,
+                                   signature: signature,
+                                   protocol_id: AUTH_PROTOCOL,
+                                   key_id: key_id,
+                                   counterparty: peer_key
+                                 })
+
+        # Authentication complete
+        session.peer_nonce        = their_nonce
+        session.peer_identity_key = peer_key
+        session.is_authenticated  = true
+        session.last_update       = current_time_ms
+
+        @session_manager.update_session(session)
+
+        nil
+      rescue BSV::Wallet::InvalidSignatureError
+        @session_manager.remove_session(session) if session
+        raise AuthError, "Initial response signature verification failed from peer: #{peer_key}"
+      end
+
+      # --- Processing: general message (we are the receiver) ---
+
+      def process_general_message(message)
+        our_nonce = fetch!(message, :your_nonce) # our session nonce echoed back
+        peer_key  = fetch!(message, :identity_key)
+        payload   = message[:payload] || message['payload'] || []
+        signature = fetch!(message, :signature)
+        msg_nonce = fetch!(message, :nonce)
+
+        # Verify the echoed nonce is one we created
+        raise AuthError, "Unable to verify nonce for general message from: #{peer_key}" unless Nonce.verify(our_nonce, @wallet)
+
+        session = @session_manager.get_session(our_nonce)
+        raise AuthError, "Session not found for nonce: #{our_nonce.inspect}" unless session
+
+        # Verify signature: signed over payload with key_id "msg_nonce session_nonce"
+        key_id = key_id_for(msg_nonce, session.session_nonce)
+
+        @wallet.verify_signature({
+                                   data: payload,
+                                   signature: signature,
+                                   protocol_id: AUTH_PROTOCOL,
+                                   key_id: key_id,
+                                   counterparty: session.peer_identity_key
+                                 })
+
+        session.last_update = current_time_ms
+        @session_manager.update_session(session)
+
+        { peer_identity_key: session.peer_identity_key, payload: payload }
+      rescue BSV::Wallet::InvalidSignatureError
+        raise AuthError, "General message signature verification failed from: #{peer_key}"
+      end
+
+      # --- Helpers ---
+
+      # Builds the key ID string: "prefix suffix".
+      # @param prefix [String] first nonce (base64)
+      # @param suffix [String] second nonce (base64)
+      # @return [String]
+      def key_id_for(prefix, suffix)
+        "#{prefix} #{suffix}"
+      end
+
+      # Decodes a base64 string to a byte array (Array<Integer>).
+      # @param b64 [String]
+      # @return [Array<Integer>]
+      def b64_decode(b64)
+        ::Base64.strict_decode64(b64).bytes
+      end
+
+      # Fetches a value from a message hash, trying both Symbol and String keys.
+      # @param message [Hash]
+      # @param key [Symbol]
+      # @return [Object]
+      # @raise [AuthError] if the key is missing or nil
+      def fetch!(message, key)
+        value = message[key] || message[key.to_s]
+        raise AuthError, "Missing required field: #{key}" if value.nil?
+        raise AuthError, "Field #{key} must not be empty" if value.respond_to?(:empty?) && value.empty?
+
+        value
+      end
+
+      def certifiers_present?
+        certs = @certificates_to_request[:certifiers] || @certificates_to_request['certifiers']
+        certs.is_a?(Array) && !certs.empty?
+      end
+
+      def current_time_ms
+        (Time.now.to_f * 1000).to_i
+      end
+    end
+  end
+end

data/lib/bsv/auth/peer_session.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module BSV
+  module Auth
+    # Represents the state of an authentication session with a peer.
+    #
+    # Sessions are indexed by +session_nonce+ (our nonce for the session),
+    # which is the primary key in {SessionManager}. The +peer_identity_key+
+    # is a secondary index used to look up sessions by peer.
+    #
+    # @example Creating a session
+    #   session = PeerSession.new(session_nonce: nonce)
+    #   session.peer_identity_key = 'abc123...'
+    #   session.peer_nonce = 'xyz...'
+    class PeerSession
+      # @return [String] our nonce for this session (base64) — primary key
+      attr_reader :session_nonce
+
+      # @return [String, nil] the peer's identity key (public key hex)
+      attr_accessor :peer_identity_key
+
+      # @return [String, nil] the nonce we received from the peer (base64)
+      attr_accessor :peer_nonce
+
+      # @return [Boolean] whether mutual authentication is complete
+      attr_accessor :is_authenticated
+
+      # @return [Integer] Unix timestamp (milliseconds) of last update
+      attr_accessor :last_update
+
+      # @return [Boolean] whether certificates are required from this peer
+      attr_accessor :certificates_required
+
+      # @return [Boolean] whether required certificates have been validated
+      attr_accessor :certificates_validated
+
+      # @param session_nonce [String] our nonce for this session (base64)
+      def initialize(session_nonce:)
+        @session_nonce          = session_nonce
+        @peer_identity_key      = nil
+        @peer_nonce             = nil
+        @is_authenticated       = false
+        @last_update            = current_time_ms
+        @certificates_required  = false
+        @certificates_validated = true
+      end
+
+      # @return [Boolean]
+      def authenticated?
+        @is_authenticated
+      end
+
+      private
+
+      def current_time_ms
+        (Time.now.to_f * 1000).to_i
+      end
+    end
+  end
+end

data/lib/bsv/auth/session_manager.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module BSV
+  module Auth
+    # Thread-safe store for {PeerSession} objects.
+    #
+    # Supports dual-index lookup: by +session_nonce+ (primary) or by
+    # +peer_identity_key+ (secondary). Multiple concurrent sessions per
+    # peer identity key are supported — the most recently updated session
+    # is returned when looking up by identity key.
+    #
+    # Matches the ts-sdk SessionManager dual-index design.
+    class SessionManager
+      def initialize
+        # session_nonce -> PeerSession
+        @by_nonce    = {}
+        # peer_identity_key -> Set of session_nonces
+        @by_identity = {}
+        @mutex       = Mutex.new
+      end
+
+      # Adds a session to the manager.
+      #
+      # @param session [PeerSession]
+      # @raise [ArgumentError] if +session_nonce+ is blank
+      def add_session(session)
+        raise ArgumentError, 'session_nonce is required' unless session.session_nonce.is_a?(String) && !session.session_nonce.empty?
+
+        @mutex.synchronize do
+          @by_nonce[session.session_nonce] = session
+
+          if session.peer_identity_key.is_a?(String)
+            nonces = @by_identity[session.peer_identity_key] ||= []
+            nonces << session.session_nonce unless nonces.include?(session.session_nonce)
+          end
+        end
+      end
+
+      # Updates an existing session (removes old references and re-adds).
+      #
+      # @param session [PeerSession]
+      def update_session(session)
+        @mutex.synchronize do
+          remove_session_locked(session)
+          add_session_locked(session)
+        end
+      end
+
+      # Retrieves a session by +session_nonce+ or +peer_identity_key+.
+      #
+      # When the identifier is a session nonce, returns that exact session.
+      # When the identifier is a peer identity key, returns the most recently
+      # updated session for that peer.
+      #
+      # @param identifier [String]
+      # @return [PeerSession, nil]
+      def get_session(identifier)
+        @mutex.synchronize do
+          direct = @by_nonce[identifier]
+          return direct if direct
+
+          nonces = @by_identity[identifier]
+          return nil if nonces.nil? || nonces.empty?
+
+          best = nil
+          nonces.each do |nonce|
+            s = @by_nonce[nonce]
+            next if s.nil?
+
+            best = s if best.nil? || (s.last_update || 0) > (best.last_update || 0)
+          end
+          best
+        end
+      end
+
+      # Removes a session from the manager.
+      #
+      # @param session [PeerSession]
+      def remove_session(session)
+        @mutex.synchronize { remove_session_locked(session) }
+      end
+
+      # @param identifier [String] session nonce or identity key
+      # @return [Boolean]
+      def session?(identifier)
+        @mutex.synchronize do
+          return true if @by_nonce.key?(identifier)
+
+          nonces = @by_identity[identifier]
+          !nonces.nil? && !nonces.empty?
+        end
+      end
+
+      private
+
+      def add_session_locked(session)
+        return unless session.session_nonce.is_a?(String) && !session.session_nonce.empty?
+
+        @by_nonce[session.session_nonce] = session
+
+        return unless session.peer_identity_key.is_a?(String)
+
+        nonces = @by_identity[session.peer_identity_key] ||= []
+        nonces << session.session_nonce unless nonces.include?(session.session_nonce)
+      end
+
+      def remove_session_locked(session)
+        @by_nonce.delete(session.session_nonce)
+
+        return unless session.peer_identity_key.is_a?(String)
+
+        nonces = @by_identity[session.peer_identity_key]
+        return unless nonces
+
+        nonces.delete(session.session_nonce)
+        @by_identity.delete(session.peer_identity_key) if nonces.empty?
+      end
+    end
+  end
+end

data/lib/bsv/auth/transport.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BSV
+  module Auth
+    # Duck-typed interface for BRC-31 message transport.
+    #
+    # Concrete transports (HTTP, WebSocket, in-process, etc.) must implement
+    # both methods. Include this module to get the default +NotImplementedError+
+    # stubs — override in your implementation class.
+    #
+    # @example Minimal in-process transport for testing
+    #   class DirectTransport
+    #     include BSV::Auth::Transport
+    #
+    #     def initialize(peer)
+    #       @peer = peer
+    #     end
+    #
+    #     def send(message)
+    #       @peer.handle_incoming_message(message)
+    #     end
+    #
+    #     def on_data(&block)
+    #       @on_data = block
+    #     end
+    #   end
+    module Transport
+      # Sends a message to the remote peer.
+      #
+      # @param message [Hash] the serialised auth message
+      # @return [void]
+      def send(_message)
+        raise NotImplementedError, "#{self.class}#send not implemented"
+      end
+
+      # Registers a callback to be invoked when a message arrives.
+      #
+      # @yieldparam message [Hash] the incoming auth message
+      # @return [void]
+      def on_data(&_block)
+        raise NotImplementedError, "#{self.class}#on_data not implemented"
+      end
+    end
+  end
+end

data/lib/bsv/auth.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BSV
+  module Auth
+    autoload :AuthError,      'bsv/auth/auth_error'
+    autoload :Nonce,          'bsv/auth/nonce'
+    autoload :PeerSession,    'bsv/auth/peer_session'
+    autoload :SessionManager, 'bsv/auth/session_manager'
+    autoload :Transport,      'bsv/auth/transport'
+    autoload :Peer,           'bsv/auth/peer'
+
+    # Protocol version
+    AUTH_VERSION = '0.1'
+
+    # Message type string constants (matching ts-sdk/go-sdk)
+    MSG_INITIAL_REQUEST  = 'initialRequest'
+    MSG_INITIAL_RESPONSE = 'initialResponse'
+    MSG_CERT_REQUEST     = 'certificateRequest'
+    MSG_CERT_RESPONSE    = 'certificateResponse'
+    MSG_GENERAL          = 'general'
+  end
+end

data/lib/bsv/primitives/extended_key.rb

@@ -212,7 +212,10 @@ module BSV
 
         components[1..].reduce(self) do |key, component|
           hardened = component.end_with?("'", 'H', 'h')
-          index = component.to_i
+          numeric_part = component.delete("'Hh")
+          raise ArgumentError, "invalid path component: '#{component}'" unless numeric_part.match?(/\A\d+\z/)
+
+          index = numeric_part.to_i
           index += HARDENED if hardened
           key.child(index)
         end