bsv-sdk 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b45240189e3a6531b7273ee4df823490c1f892ae332257743b74783f2e88ef87
-  data.tar.gz: b3ffa3feb075fb232b87a50149af07139ef01d1d80edb03c7e595f758fe01a84
+  metadata.gz: 5d32b117209fc6509e5020811725c5b5bb5e776c57fbd0f3cb0afa8cf3cc12ca
+  data.tar.gz: 2fa913c8e3fe270b53a1748e2ff4bdb8055945b625a9e3075eb293b78d581fe4
 SHA512:
-  metadata.gz: 28cb3358d0483ad4574e1ef3a57c6f85f45e4404de0a70faea6e8b431b9c47655b490e73f4779ca74a617e35bcdadd65eb7f5e2cbd9310199a3af494af4a9187
-  data.tar.gz: 5a4f40bf35ba4dc93a260c6729871a165ebb4e468b802f664371bcf0574d3aacf23d91f8ca9634a739af6cd4443e8b264b9256a2888ddfd725289f98a606b3a9
+  metadata.gz: 82e8ca0cf9e266d7c80fe8be42be40450e5a3495db083f90aa098aaf7ff0186ecc4a63b3a1efd9b7447738d857b930f655be291ad098a83ef7a6d0095df0b4d0
+  data.tar.gz: 103b3246361a57c3b1161c789c097c147b6c7070781094587f59bdee6caf3141bb5b22934a89e1bfdd4e514b4f45eb2edd1ae218fc92f23e2d520a3a56f72113

data/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-04-01
+
+### Added
+
+#### Primitives
+
+- **Bitcore ECIES** — `ECIES.bitcore_encrypt` / `ECIES.bitcore_decrypt`. AES-256-CBC with random IV, SHA-512(X-coordinate) key derivation. Matches ts-sdk and go-sdk Bitcore variants.
+
+#### Transaction
+
+- **LivePolicy.default** — one-line convenience for live fee queries via GorillaPool ARC with 5-minute cache and 100 sat/kB fallback.
+
+### Changed
+
+- **Default fee rate**: `SatoshisPerKilobyte` default changed from 50 to 100 sat/kB (matches ts-sdk LivePolicy fallback). `Wallet#fund` default changed from 0.5 to 0.1 sat/byte.
+
+### bsv-wallet v0.2.0
+
+- **FileStore** — JSON file-backed persistent storage, now the default for `WalletClient`. Data survives process restarts. MemoryStore becomes explicit opt-in for tests.
+- **File permissions** — directory created with 0700, files with 0600. Warns via Logger on startup if permissions are too open.
+- **BRC-31 Auth/Peer** — mutual authentication with nonce-based challenges, ECDSA signatures, and session management.
+- **Wire protocol** — binary ABI serialisation for all 28 BRC-100 methods (call codes 1-28, VarInt encoding).
+- **Certificate issuance** — `acquire_certificate` with `'issuance'` protocol (POST to certifier URL).
+- **OpCat template** — OP_CAT concatenation script template with lock/unlock constructors.
+- **Live fee policy** — `LivePolicy` fee model fetching from ARC `/v1/policy`.
+
+### Fixed
+
+- Subject and certifier pinned in certificate issuance response (not overridable by remote certifier)
+- Wire reader negative privileged_reason length crash
+- PUSHDATA1/2/4 bounds check (silent data corruption on truncated scripts)
+- Extended key path validation (reject non-numeric indices)
+
+## [0.3.0] - 2026-03-27
+
+### Added
+
+#### Primitives
+
+- **SymmetricKey** — AES-256-GCM encryption/decryption with 32-byte IV (cross-SDK compatible). Construct from random, ECDH, or raw bytes.
+- **BRC-77 SignedMessage** — authenticated message signing and verification using BRC-42 derived keys. Supports targeted (specific verifier) and "anyone" modes.
+- **BRC-78 EncryptedMessage** — end-to-end encrypted messaging using ECDH-derived symmetric keys.
+- **Schnorr ZKP (BRC-94)** — zero-knowledge proof of ECDH shared secret knowledge. `Schnorr.generate_proof` / `Schnorr.verify_proof`.
+- **Shamir's Secret Sharing** — split private keys into threshold shares (`PrivateKey#to_key_shares`) with Lagrange interpolation reconstruction. Backup format with integrity check.
+
+#### Script
+
+- **PushDrop template** — data carrier with P2PK spending. `Script.pushdrop_lock` / `Script.pushdrop_unlock` with field extraction.
+- **RPuzzle template** — R-puzzle hash-based spending with 6 hash type variants (raw, SHA1, SHA256, RIPEMD160, HASH160, HASH256).
+
+#### Transaction
+
+- **Benford's law change distribution** — privacy-preserving change output splitting using Benford's first-digit distribution.
+- **ARC X-WaitFor** — `ARC#broadcast` gains `wait_for:` parameter for `X-WaitFor` header (RECEIVED, STORED, ANNOUNCED_TO_NETWORK, SEEN_ON_NETWORK, MINED).
+
+### Fixed
+
+- Empty plaintext/ciphertext handling on older OpenSSL versions
+- PushDrop detection for minimally-encoded fields
+
+### Changed
+
+- `Transaction#fee` change distribution uses Benford's law (was equal split)
+- `LineLength` raised to 150
+
 ## [0.2.1] - 2026-03-07
 
 ### Fixed

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