noise-ruby 0.14.0 → 0.15.0

data/lib/noise/exceptions.rb

@@ -4,16 +4,22 @@ module Noise
   module Exceptions
     autoload :DecryptError, 'noise/exceptions/decrypt_error'
     autoload :EncryptError, 'noise/exceptions/encrypt_error'
+    autoload :HandshakeAlreadyFinishedError, 'noise/exceptions/handshake_already_finished_error'
+    autoload :HandshakeNotFinishedError, 'noise/exceptions/handshake_not_finished_error'
+    autoload :HandshakeNotStartedError, 'noise/exceptions/handshake_not_started_error'
+    autoload :HandshakeTurnError, 'noise/exceptions/handshake_turn_error'
     autoload :InvalidNonceError, 'noise/exceptions/invalid_nonce_error'
     autoload :InvalidPublicKeyError, 'noise/exceptions/invalid_public_key_error'
     autoload :MaxNonceError, 'noise/exceptions/max_nonce_error'
     autoload :MessageTooLongError, 'noise/exceptions/message_too_long_error'
     autoload :MissingDependencyError, 'noise/exceptions/missing_dependency_error'
     autoload :ProtocolNameError, 'noise/exceptions/protocol_name_error'
+    autoload :ReadTimeoutError, 'noise/exceptions/read_timeout_error'
     autoload :NoiseHandshakeError, 'noise/exceptions/noise_handshake_error'
     autoload :NoiseValidationError, 'noise/exceptions/noise_validation_error'
     autoload :NoisePSKError, 'noise/exceptions/noise_psk_error'
     autoload :PSKValueError, 'noise/exceptions/psk_value_error'
+    autoload :TruncatedMessageError, 'noise/exceptions/truncated_message_error'
     autoload :UnsupportedModifierError, 'noise/exceptions/unsupported_modifier_error'
   end
 end

data/lib/noise/pattern.rb

@@ -102,14 +102,16 @@ module Noise
   class Pattern
     attr_reader :name, :tokens, :modifiers, :psk_count, :fallback
 
-    NAME_REGEX = /\A([A-Z1]+)([^A-Z]*)\z/
-
-    def self.create(name)
-      matched = NAME_REGEX.match(name)
-      raise Noise::Exceptions::ProtocolNameError, "Malformed pattern name: #{name}" unless matched
-
-      modifiers = matched[2].split('+').map { |s| Modifier.parse(s) }
-      pattern_class(matched[1]).new(modifiers)
+    # Noise::ProtocolName tells a pattern name from the modifiers written after it, so both
+    # arrive here already separated.
+    #
+    # @param [String] name the handshake pattern name on its own, for example 'XX'.
+    # @param [Array<Noise::Modifier::Psk, Noise::Modifier::Fallback>] modifiers the modifiers to
+    #   apply to it. Call #apply_pattern_modifiers to have them rewrite the token list.
+    # @raise [Noise::Exceptions::ProtocolNameError] if no pattern goes by that name.
+    # @return [Noise::Pattern]
+    def self.create(name, modifiers = [])
+      pattern_class(name).new(modifiers)
     end
 
     def self.pattern_class(pattern)

data/lib/noise/protocol.rb

@@ -3,7 +3,7 @@
 module Noise
   class Protocol
     attr_accessor :cipher_fn, :hash_fn, :dh_fn, :hkdf_fn
-    attr_reader :name, :pattern
+    attr_reader :name, :pattern, :protocol_name
 
     CIPHER = {
       'AESGCM' => Noise::Functions::Cipher::AesGcm,
@@ -24,35 +24,59 @@ module Noise
       'BLAKE3' => Noise::Functions::Hash::Blake3
     }.freeze
 
+    # @param [String] name the protocol name, for example 'Noise_XX_25519_ChaChaPoly_SHA256'.
+    # @raise [Noise::Exceptions::ProtocolNameError] if the name is malformed, or names a pattern
+    #   or a function this gem does not implement.
+    # @raise [Noise::Exceptions::UnsupportedModifierError] if it names a modifier this gem does
+    #   not implement.
+    # @return [Noise::Protocol]
     def self.create(name)
-      parts = name.split('_')
-      raise Noise::Exceptions::ProtocolNameError, "Malformed protocol name: #{name}" unless parts.size == 5
-
-      prefix, pattern_name, dh_name, cipher_name, hash_name = parts
-      raise Noise::Exceptions::ProtocolNameError, "Malformed protocol name: #{name}" if prefix != 'Noise'
-
-      new(name, pattern_name, cipher_name, hash_name, dh_name)
+      new(Noise::ProtocolName.parse(name))
     end
 
-    def initialize(name, pattern_name, cipher_name, hash_name, dh_name)
-      @name = name
-      @pattern = Noise::Pattern.create(pattern_name)
-      @hkdf_fn = Noise::Functions::Hash.create_hkdf_fn(hash_name)
+    # @param [Noise::ProtocolName] protocol_name the parsed name this protocol runs.
+    def initialize(protocol_name)
+      @protocol_name = protocol_name
+      @name = protocol_name.name
+      @pattern = Noise::Pattern.create(protocol_name.pattern_name, protocol_name.modifiers)
+      @hkdf_fn = Noise::Functions::Hash.create_hkdf_fn(protocol_name.hash_name)
       @pattern.apply_pattern_modifiers
 
-      initialize_fn!(cipher_name, hash_name, dh_name)
+      initialize_fn!
+    end
+
+    def psk?
+      @pattern.psk?
     end
 
-    def initialize_fn!(cipher_name, hash_name, dh_name)
-      @cipher_fn = CIPHER[cipher_name]&.new
-      @hash_fn = HASH[hash_name]&.new
-      @dh_fn = DH[dh_name]&.new
+    private
+
+    # Looks the three functions up by the names the protocol name gives them.
+    #
+    # @raise [Noise::Exceptions::ProtocolNameError] if any of the three is one this gem does not
+    #   implement.
+    def initialize_fn!
+      @cipher_fn = CIPHER[@protocol_name.cipher_name]&.new
+      @hash_fn = HASH[@protocol_name.hash_name]&.new
+      @dh_fn = create_dh_fn(@protocol_name.dh_names)
       raise Noise::Exceptions::ProtocolNameError, "Unsupported function in: #{@name}" unless
         @cipher_fn && @hash_fn && @dh_fn
     end
 
-    def psk?
-      @pattern.psk?
+    # A name may list more than one DH function, joined with '+', which is how a hybrid handshake
+    # is written. This gem runs a single DH function, so any name that lists more than one, or
+    # that leaves a member of the list empty, resolves to nothing and is reported as unsupported.
+    #
+    # The hybrid names the Noise extensions define also carry a modifier, hfs, which
+    # Noise::ProtocolName rejects first, so what reaches here today is a name that lists several
+    # DH functions and nothing else.
+    #
+    # @param [Array<String>] names the DH function names the protocol name lists.
+    # @return [Object, nil] the DH function, or nil if the name asks for one this gem lacks.
+    def create_dh_fn(names)
+      return nil unless names.size == 1
+
+      DH[names.first]&.new
     end
   end
 end

data/lib/noise/protocol_name.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Noise
+  # A Noise protocol name, split into the parts that name a handshake pattern and the three
+  # functions the protocol runs on.
+  #
+  # A name has five parts joined with '_': the prefix 'Noise', the handshake pattern with its
+  # modifiers, the DH function, the cipher function and the hash function, for example
+  # 'Noise_NNpsk0_25519_ChaChaPoly_BLAKE2s'.
+  #
+  # Two of those parts hold a list of their own. The pattern part is a pattern name followed by
+  # the modifiers applied to it, and the DH part is a list joined with '+', because a hybrid
+  # handshake names two DH functions at once ('Noise_NNhfs_25519+448_ChaChaPoly_BLAKE2s'). Both
+  # are split here, so that every rule about the shape of a name lives in this class alone.
+  #
+  # Which functions exist is Noise::Protocol's question, not this one's: a name that asks for a
+  # cipher, hash or DH function this gem does not implement still parses. Modifiers are the one
+  # exception, because a modifier has to be understood before it can be held as a value, so an
+  # unknown one is rejected here.
+  #
+  # The members are the names as written, not the functions themselves. Noise::Protocol resolves
+  # them, and calls its resolved functions cipher_fn, hash_fn and dh_fn.
+  ProtocolName = Data.define(:name, :pattern_name, :modifiers, :dh_names, :cipher_name,
+                             :hash_name) do
+    # Parses a protocol name.
+    #
+    # @param [String] name for example 'Noise_XX_25519_ChaChaPoly_SHA256'.
+    # @raise [Noise::Exceptions::ProtocolNameError] if the name is not five parts with the 'Noise'
+    #   prefix and a pattern part whose modifiers can be told from the pattern name.
+    # @raise [Noise::Exceptions::UnsupportedModifierError] if a modifier is written correctly but
+    #   is not one this gem implements.
+    # @return [Noise::ProtocolName]
+    def self.parse(name)
+      # 'Noise', the pattern with its modifiers, the DH functions, the cipher and the hash.
+      parts = name.split('_')
+      malformed!(name) unless parts.size == 5
+
+      prefix, pattern_part, dh_part, cipher_name, hash_name = parts
+      malformed!(name) unless prefix == 'Noise'
+
+      # A pattern name is capitals, plus the digit 1 that deferred patterns use (X1K1). Whatever
+      # follows it is the modifiers.
+      matched = /\A([A-Z1]+)([^A-Z]*)\z/.match(pattern_part)
+      malformed!(name) unless matched
+
+      new(name: name, pattern_name: matched[1], modifiers: parse_modifiers(matched[2]),
+          dh_names: split_dh(dh_part), cipher_name: cipher_name, hash_name: hash_name)
+    end
+
+    # @param [String] part the modifiers as written, which is '' when there are none.
+    # @return [Array] the modifiers, in the order the name writes them.
+    def self.parse_modifiers(part)
+      part.split('+').map { |modifier| Modifier.parse(modifier) }.freeze
+    end
+    private_class_method :parse_modifiers
+
+    # Keeps the empty members a stray '+' leaves behind, so that '25519+' reads as two DH
+    # functions, the second of which has no name, rather than as the single function '25519'.
+    # Nothing resolves an empty name, so such a name is reported as unsupported.
+    #
+    # @param [String] part the DH functions as written.
+    # @return [Array<String>] one name per member.
+    def self.split_dh(part)
+      part.split('+', -1).freeze
+    end
+    private_class_method :split_dh
+
+    def self.malformed!(name)
+      raise Noise::Exceptions::ProtocolNameError, "Malformed protocol name: #{name}"
+    end
+    private_class_method :malformed!
+
+    # @return [String] the name this was parsed from.
+    def to_s
+      name
+    end
+  end
+end

data/lib/noise/transport/bolt8.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Noise
+  module Transport
+    # The BOLT #8 transport layer, which turns the message-oriented Noise::Connection into the
+    # byte stream the Lightning Network sends over TCP.
+    #
+    # A Lightning message goes out as two Noise messages: the length of the payload as a two-byte
+    # big-endian integer, encrypted on its own, and then the payload. The receiver decrypts the
+    # first to learn how many bytes to read for the second. Each direction rotates its key on a
+    # schedule of its own, so that a key stolen later cannot decrypt what came before it.
+    #
+    # Run the handshake with Noise::Connection first, and wrap the finished connection:
+    #
+    #   connection = Noise::Connection::Initiator.new(Noise::Transport::Bolt8::PROTOCOL_NAME,
+    #                                                 keypairs: { s: local_static, rs: node_id })
+    #   connection.prologue = Noise::Transport::Bolt8::PROLOGUE
+    #   connection.start_handshake
+    #   # ... exchange the three handshake messages over the socket ...
+    #   transport = Noise::Transport::Bolt8.new(connection, socket)
+    #
+    #   transport.write('a lightning message')
+    #   message = transport.read
+    #
+    # The transport takes over the connection's transport phase: it holds the very CipherStates
+    # the connection does, so once one is wrapped, stop calling the connection's #encrypt,
+    # #decrypt, nonce accessors and rekey methods. Every one of them moves the same key and nonce,
+    # and the peer has no way to learn that they did.
+    #
+    # One transport belongs to one thread, for the reason Noise::Connection::Base gives.
+    class Bolt8
+      # BOLT #8 fixes the handshake to this protocol, and this prologue.
+      PROTOCOL_NAME = 'Noise_XK_secp256k1_ChaChaPoly_SHA256'
+      PROLOGUE = 'lightning'
+
+      # The payload length goes out as a two-byte big-endian integer, so the header is those two
+      # bytes plus the authentication tag over them.
+      LENGTH_PREFIX_LENGTH = 2
+      HEADER_LENGTH = LENGTH_PREFIX_LENGTH + Noise::State::CipherState::TAG_LENGTH
+
+      # What two bytes of length can express, and what BOLT #8 allows a Lightning message to be.
+      # Its authentication tag brings such a message to 65551 bytes, past the 65535 a single Noise
+      # transport message may be, so Noise::Connection#encrypt would refuse the largest messages
+      # the Lightning Network permits. That is why this class encrypts through the CipherState.
+      MAX_PAYLOAD_LENGTH = 65_535
+
+      # @param [Noise::Connection::Base] connection a finished BOLT #8 handshake.
+      # @param [IO] io the stream to read from and write to. See Noise::Transport::Stream.
+      # @param [Numeric, nil] read_timeout how long #read waits for the next bytes of a message
+      #   before giving up, in seconds. See Noise::Transport::Stream.
+      # @raise [Noise::Exceptions::HandshakeNotFinishedError] if the handshake has not finished.
+      # @raise [Noise::Exceptions::ProtocolNameError] if the connection runs another protocol.
+      # @raise [Noise::Exceptions::NoiseValidationError] if the connection is half-duplex.
+      # @raise [ArgumentError] if read_timeout is negative, or if the IO cannot be waited on.
+      def initialize(connection, io, read_timeout: nil)
+        validate(connection)
+
+        @stream = Stream.new(io, read_timeout: read_timeout)
+        hkdf_fn = connection.protocol.hkdf_fn
+        # Both directions start from the chaining key the handshake ended with, and rotate away
+        # from it independently.
+        @send = Direction.new(connection.cipher_state_encrypt, connection.chaining_key, hkdf_fn)
+        @receive = Direction.new(connection.cipher_state_decrypt, connection.chaining_key, hkdf_fn)
+      end
+
+      # Encrypts one Lightning message and writes it to the IO: the encrypted length, then the
+      # encrypted payload. It returns once all of it has gone out.
+      #
+      # @param [String] payload the message, at most MAX_PAYLOAD_LENGTH bytes.
+      # @raise [Noise::Exceptions::MessageTooLongError] if the payload is longer than that.
+      # @raise [IOError] if the IO accepts none of the bytes it is handed.
+      # @return [Integer] how many bytes were written.
+      def write(payload)
+        if payload.bytesize > MAX_PAYLOAD_LENGTH
+          raise Noise::Exceptions::MessageTooLongError,
+                "Message is #{payload.bytesize} bytes, which exceeds the maximum of #{MAX_PAYLOAD_LENGTH}."
+        end
+
+        @stream.write(@send.encrypt([payload.bytesize].pack('n')) + @send.encrypt(payload))
+      end
+
+      # Reads one Lightning message, blocking until all of it has arrived.
+      #
+      # Every failure ends the transport. BOLT #8 requires the connection to be closed on a
+      # decryption failure, and a message that stops part way through leaves the stream in the
+      # middle of one, where the next read would take a payload for a length.
+      #
+      # An error the IO itself raises, such as Errno::ECONNRESET, comes through as it is.
+      #
+      # @raise [Noise::Exceptions::TruncatedMessageError] if the stream ends part way through a
+      #   message.
+      # @raise [Noise::Exceptions::ReadTimeoutError] if no more bytes arrive in time.
+      # @raise [Noise::Exceptions::DecryptError] if either half fails to authenticate.
+      # @return [String, nil] the payload, or nil if the stream ended between messages.
+      def read
+        header = @stream.read_exactly_or_nil(HEADER_LENGTH)
+        return nil if header.nil?
+
+        length = @receive.decrypt(header).unpack1('n')
+        @receive.decrypt(@stream.read_exactly(length + Noise::State::CipherState::TAG_LENGTH))
+      end
+
+      private
+
+      # BOLT #8 gives each direction a key, a nonce and a chaining key of its own, so a half-duplex
+      # connection, which shares one CipherState both ways, cannot carry it. Two Directions over
+      # one CipherState would advance a single nonce on both sending and receiving, and rotate to
+      # two different chaining keys, which no BOLT #8 peer would follow. Two such parties still
+      # talk to each other, so nothing but this check would report it.
+      #
+      # @param [Noise::Connection::Base] connection the connection to wrap.
+      # @return [void]
+      def validate(connection)
+        unless connection.handshake_finished?
+          raise Noise::Exceptions::HandshakeNotFinishedError, 'The handshake has not finished.'
+        end
+
+        unless connection.protocol.name == PROTOCOL_NAME
+          raise Noise::Exceptions::ProtocolNameError,
+                "BOLT #8 runs #{PROTOCOL_NAME}, not #{connection.protocol.name}."
+        end
+
+        return unless connection.half_duplex?
+
+        raise Noise::Exceptions::NoiseValidationError,
+              'BOLT #8 gives each direction a key of its own, so it cannot run half-duplex.'
+      end
+
+      # One direction of the transport: the key it encrypts or decrypts with, and the chaining key
+      # the next one is derived from. BOLT #8 calls these sk and sck for sending, rk and rck for
+      # receiving, and rotates each direction on its own count.
+      class Direction
+        # BOLT #8 rotates a key once the nonce dedicated to it reaches 1000. A Lightning message
+        # is encrypted twice, once for its length and once for its payload, so that is every 500
+        # messages.
+        KEY_ROTATION_NONCE = 1000
+
+        # @param [Noise::State::CipherState] cipher_state the transport CipherState Split() gave
+        #   this direction.
+        # @param [String] chaining_key the chaining key the handshake ended with.
+        # @param [Proc] hkdf_fn the protocol's HKDF.
+        def initialize(cipher_state, chaining_key, hkdf_fn)
+          @cipher_state = cipher_state
+          @chaining_key = chaining_key
+          @hkdf_fn = hkdf_fn
+        end
+
+        # @param [String] plaintext
+        # @return [String] the ciphertext and its authentication tag.
+        def encrypt(plaintext)
+          @cipher_state.encrypt_with_ad('', plaintext).tap { rotate_key_if_due }
+        end
+
+        # @param [String] ciphertext
+        # @raise [Noise::Exceptions::DecryptError] if it fails to authenticate, in which case the
+        #   key is not rotated and the nonce does not move.
+        # @return [String] the plaintext.
+        def decrypt(ciphertext)
+          @cipher_state.decrypt_with_ad('', ciphertext).tap { rotate_key_if_due }
+        end
+
+        private
+
+        # Replaces this direction's key with HKDF(ck, k), which also restarts the nonce at zero.
+        # This is not Noise's REKEY(k): it draws on the chaining key, so a key stolen now says
+        # nothing about the keys the direction used before it.
+        #
+        # @return [void]
+        def rotate_key_if_due
+          # Every message through this class advances the nonce by one, so the test could be an
+          # equality. It is not, so that a nonce moved from outside cannot carry the direction
+          # past the point it rotates at and leave it on one key for good.
+          return unless @cipher_state.n >= KEY_ROTATION_NONCE
+
+          @chaining_key, key = @hkdf_fn.call(@chaining_key, @cipher_state.k, 2)
+          @cipher_state.initialize_key(key)
+          nil
+        end
+      end
+      private_constant :Direction
+    end
+  end
+end

data/lib/noise/transport/framed.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Noise
+  module Transport
+    # A Noise connection framed for a byte stream: every message goes out preceded by its length,
+    # so that the reader knows how many bytes to take before decrypting.
+    #
+    #   transport = Noise::Transport::Framed.new(connection, socket)
+    #   transport.write('a message')
+    #   message = transport.read
+    #
+    # The connection learns nothing about the IO, and this class learns nothing about the
+    # handshake: it takes one that has already finished.
+    #
+    # The length goes out in the clear, as two big-endian bytes. It is not secret in any useful
+    # sense — anyone watching the stream can time the bytes and count them either way — but it does
+    # mean this framing hides nothing about how long each message is. A protocol that has to hide
+    # its message sizes pads them, or encrypts the length as BOLT #8 does.
+    #
+    # Two bytes are enough because a Noise transport message may not exceed 65535 bytes, so a
+    # length this can express is never one the connection would refuse. The payload limit is lower
+    # by the authentication tag, and Noise::Connection#encrypt is what enforces it.
+    #
+    # This class holds the connection's transport phase, so once a connection is framed, stop
+    # calling its #encrypt and #decrypt directly: a message that goes out unframed leaves the
+    # reader taking the next message's bytes for a length. One transport belongs to one thread,
+    # for the reason Noise::Connection::Base gives.
+    class Framed
+      # The length prefix, as two big-endian bytes.
+      LENGTH_PREFIX_LENGTH = 2
+
+      # The longest payload #write takes, which is a Noise transport message less its tag. Two
+      # bytes of length cannot announce more than the 65535 a transport message may be, so a
+      # declared length is never one the connection would refuse.
+      MAX_PAYLOAD_LENGTH = Noise::Connection::Base::MAX_PLAINTEXT_LENGTH
+
+      # @param [Noise::Connection::Base] connection a connection whose handshake has finished.
+      # @param [IO] io the stream to read from and write to. See Noise::Transport::Stream.
+      # @param [Numeric, nil] read_timeout how long #read waits for the next bytes of a frame
+      #   before giving up, in seconds. See Noise::Transport::Stream.
+      # @raise [Noise::Exceptions::HandshakeNotFinishedError] if the handshake has not finished.
+      # @raise [ArgumentError] if read_timeout is negative, or if the IO cannot be waited on and
+      #   the timeout would therefore do nothing.
+      def initialize(connection, io, read_timeout: nil)
+        unless connection.handshake_finished?
+          raise Noise::Exceptions::HandshakeNotFinishedError, 'The handshake has not finished.'
+        end
+
+        @connection = connection
+        @stream = Stream.new(io, read_timeout: read_timeout)
+      end
+
+      # Encrypts one message and writes it to the IO, preceded by its length. It returns once the
+      # whole frame has been written, however many writes that takes.
+      #
+      # An error the IO itself raises, such as Errno::EPIPE when the peer has gone, comes through
+      # as it is.
+      #
+      # @param [String] payload at most MAX_PAYLOAD_LENGTH bytes.
+      # @raise [Noise::Exceptions::MessageTooLongError] if the payload is longer than that.
+      # @raise [IOError] if the IO accepts none of the bytes it is handed, which no IO that keeps
+      #   its side of the bargain does.
+      # @return [Integer] how many bytes were written, the payload plus its tag and its length.
+      def write(payload)
+        ciphertext = @connection.encrypt(payload)
+
+        @stream.write([ciphertext.bytesize].pack('n') + ciphertext)
+      end
+
+      # Reads one message, waiting until all of it has arrived.
+      #
+      # Every failure ends the transport, for a different reason each time. A DecryptError says
+      # the frame was not written by the party this connection shares a key with, or not written
+      # in the order it claims; the stream is still at a frame boundary and the nonce has not
+      # moved, so reading on is possible, but reading on from a peer that just failed to
+      # authenticate is not something to do. A TruncatedMessageError or a ReadTimeoutError leaves
+      # the bytes already taken out of the stream and nowhere to put them, so the next read would
+      # take the middle of a frame for a length. Build a new connection instead.
+      #
+      # An error the IO itself raises, such as Errno::ECONNRESET when the peer disappears without
+      # closing, comes through as it is rather than as one of these.
+      #
+      # @raise [Noise::Exceptions::TruncatedMessageError] if the stream ends part way through a
+      #   frame.
+      # @raise [Noise::Exceptions::ReadTimeoutError] if no more bytes arrive in time.
+      # @raise [Noise::Exceptions::DecryptError] if the frame fails to authenticate, which is also
+      #   how a length too short to hold an authentication tag is reported.
+      # @return [String, nil] the payload, or nil if the stream ended between frames, which is how
+      #   the other party closes without cutting a message in half.
+      def read
+        prefix = @stream.read_exactly_or_nil(LENGTH_PREFIX_LENGTH)
+        return nil if prefix.nil?
+
+        @connection.decrypt(@stream.read_exactly(prefix.unpack1('n')))
+      end
+    end
+  end
+end

data/lib/noise/transport/stream.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Noise
+  module Transport
+    # The IO a framed transport sits on, and the only place that deals with the ways a stream
+    # differs from a message: it hands over fewer bytes than were asked for, takes fewer than it
+    # was given, ends in the middle of something, or goes quiet.
+    #
+    # A transport holds one of these and asks it for whole frames. Like the transport above it,
+    # one belongs to one thread: a stream has a position, and two threads reading it take halves
+    # of each other's frames.
+    class Stream
+      # @param [IO] io the stream. Anything that answers #write and #readpartial will do, which is
+      #   what makes a StringIO usable in a test.
+      # @param [Numeric, nil] read_timeout how long to wait for the next bytes before giving up,
+      #   in seconds. nil waits as long as the IO does. It applies to each wait rather than to a
+      #   frame as a whole, so a peer that sends a byte at a time holds a read open without ever
+      #   tripping it.
+      # @raise [ArgumentError] if read_timeout is negative, or if the IO cannot be waited on and
+      #   the timeout would therefore do nothing.
+      def initialize(io, read_timeout: nil)
+        validate_read_timeout!(io, read_timeout)
+
+        @io = io
+        @read_timeout = read_timeout
+      end
+
+      # Writes all of it, however many writes that takes.
+      #
+      # @param [String] frame the bytes to write.
+      # @raise [IOError] if a write takes none of them, which would otherwise spin here forever.
+      # @return [Integer] frame.bytesize, once all of it has gone out.
+      def write(frame)
+        written = 0
+        while written < frame.bytesize
+          taken = @io.write(frame.byteslice(written, frame.bytesize - written))
+          raise IOError, "#{@io.class} took #{taken.inspect} of the #{frame.bytesize} bytes it was given." unless
+            taken.is_a?(Integer) && taken.positive?
+
+          written += taken
+        end
+        written
+      end
+
+      # @param [Integer] length how many bytes to read.
+      # @raise [Noise::Exceptions::TruncatedMessageError] if the stream ends first.
+      # @raise [Noise::Exceptions::ReadTimeoutError] if no more arrive in time.
+      # @return [String] exactly length bytes.
+      def read_exactly(length)
+        gather(length) || truncated!(length, 0)
+      end
+
+      # The same, for the first bytes of a frame, where a stream that has ended has not been cut
+      # short: it is the other party saying goodbye between one frame and the next.
+      #
+      # @param [Integer] length how many bytes to read.
+      # @raise [Noise::Exceptions::TruncatedMessageError] if the stream ends after some of them.
+      # @raise [Noise::Exceptions::ReadTimeoutError] if no more arrive in time.
+      # @return [String, nil] exactly length bytes, or nil if the stream had already ended.
+      def read_exactly_or_nil(length)
+        gather(length)
+      end
+
+      private
+
+      # @param [Integer] length how many bytes to read.
+      # @raise [Noise::Exceptions::TruncatedMessageError] if the stream ends after some of them.
+      # @return [String, nil] the bytes, or nil if the stream ended before any of them arrived.
+      def gather(length)
+        # Binary, because a frame is bytes: appending a chunk to a buffer of another encoding
+        # would count characters where this counts bytes.
+        buffer = ''.b
+        while buffer.bytesize < length
+          chunk = read_chunk(length - buffer.bytesize)
+          return buffer.empty? ? nil : truncated!(length, buffer.bytesize) if chunk.nil?
+
+          buffer << chunk
+        end
+        buffer
+      end
+
+      # @param [Integer] length how many bytes were needed.
+      # @param [Integer] arrived how many turned up.
+      # @raise [Noise::Exceptions::TruncatedMessageError] always.
+      def truncated!(length, arrived)
+        raise Noise::Exceptions::TruncatedMessageError,
+              "Needed #{length} bytes, the stream ended after #{arrived}."
+      end
+
+      # Takes whatever has arrived, which on a socket is rarely a whole frame at once.
+      #
+      # @param [Integer] length the most to take.
+      # @return [String, nil] the bytes, or nil at end of stream.
+      def read_chunk(length)
+        wait_readable
+        @io.readpartial(length)
+      rescue EOFError
+        nil
+      end
+
+      # Asks the IO itself to wait, rather than selecting on its file descriptor, because bytes it
+      # has already read and buffered are ready to be taken while the descriptor is quiet.
+      #
+      # @raise [Noise::Exceptions::ReadTimeoutError] if nothing arrives within read_timeout.
+      # @return [void]
+      def wait_readable
+        return if @read_timeout.nil?
+        return if @io.wait_readable(@read_timeout)
+
+        raise Noise::Exceptions::ReadTimeoutError,
+              "No more of the frame arrived within #{@read_timeout} seconds."
+      end
+
+      # @param [IO] io the stream this was given.
+      # @param [Numeric, nil] read_timeout the timeout it was given.
+      # @raise [ArgumentError] if the timeout could not be honoured as asked.
+      # @return [void]
+      def validate_read_timeout!(io, read_timeout)
+        return if read_timeout.nil?
+
+        raise ArgumentError, "read_timeout is #{read_timeout}, which is not a length of time." if read_timeout.negative?
+        return if io.respond_to?(:wait_readable)
+
+        raise ArgumentError,
+              "read_timeout cannot be honoured on a #{io.class}, which does not answer #wait_readable. " \
+              'Leave it out, or pass an IO that does.'
+      end
+    end
+  end
+end

data/lib/noise/transport.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Noise
+  # The layers that put a Noise::Connection on top of an IO. A connection encrypts and decrypts
+  # whole messages, which is the shape the Noise specification describes but not the shape a
+  # socket has, so something has to say where one message ends and the next begins.
+  # Stream is not one of those layers but the thing they stand on: the IO, and the ways a stream
+  # differs from a message.
+  module Transport
+    autoload :Bolt8, 'noise/transport/bolt8'
+    autoload :Framed, 'noise/transport/framed'
+    autoload :Stream, 'noise/transport/stream'
+  end
+end

data/lib/noise/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Noise
-  VERSION = '0.14.0'
+  VERSION = '0.15.0'
 end

data/lib/noise.rb

@@ -15,9 +15,14 @@ module Noise
   autoload :KeyPair, 'noise/key_pair'
   autoload :Protocol, 'noise/protocol'
   autoload :Pattern, 'noise/pattern'
+  # Noise::Modifier and Noise::Token are declared in the same file as Noise::Pattern.
+  autoload :Modifier, 'noise/pattern'
+  autoload :Token, 'noise/pattern'
+  autoload :ProtocolName, 'noise/protocol_name'
   autoload :Exceptions, 'noise/exceptions'
   autoload :Functions, 'noise/functions'
   autoload :State, 'noise/state'
+  autoload :Transport, 'noise/transport'
 
   # Some DH and hash functions are backed by a gem, and often a system library, that is only needed
   # when the function appears in a protocol name. Loading one is therefore allowed to fail; the