snell 0.1.0

data/lib/snell/limits.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Snell
+  # Ruby API 使用的不可变资源预算：时间以秒计，容量以字节计；
+  # 只有 pool_max_idle 允许为零，表示不保留空闲连接。
+  class Limits
+    DEFAULTS = {
+      max_connections: 2048, handshake_concurrency: 64,
+      handshake_rate: 100, handshake_burst: 200, udp_associations: 256,
+      buffer_bytes: 131_072, dial_timeout: 10, handshake_timeout: 10,
+      idle_timeout: 300, pool_max_idle: 10, pool_idle_timeout: 180,
+      drain_timeout: 2, drain_max_bytes: 524_288, shutdown_grace: 30
+    }.freeze
+    INTEGERS = %i[max_connections handshake_concurrency handshake_burst udp_associations
+                  buffer_bytes pool_max_idle drain_max_bytes].freeze
+
+    def initialize(values = {})
+      raise ArgumentError, "limits must be a Hash" unless values.is_a?(Hash)
+      raise ArgumentError, "Invalid limit name" unless values.keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+
+      values = values.to_h.transform_keys(&:to_sym)
+      unknown = values.keys - DEFAULTS.keys
+      raise ArgumentError, "Unknown limits: #{unknown.join(', ')}" unless unknown.empty?
+
+      @values = DEFAULTS.merge(values).freeze
+      @values.each do |name, value|
+        valid = value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+        valid &&= value.is_a?(Integer) if INTEGERS.include?(name)
+        valid ||= name == :pool_max_idle && value.is_a?(Integer) && value.zero?
+        raise ArgumentError, "Invalid limit #{name}" unless valid
+      end
+      freeze
+    end
+
+    def [](name)
+      @values.fetch(name)
+    end
+
+    def to_h
+      @values.dup
+    end
+  end
+end

data/lib/snell/obfuscation.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Snell
+  # 旧版协议可选的外层混淆；HTTP/TLS 形态不提供证书认证，
+  # 也不建立安全 TLS 会话。
+  module Obfuscation
+    module_function
+
+    def wrap(transport, role:, mode: nil, kind: nil, host: nil, uri: "/")
+      raise ArgumentError, "conflicting obfuscation modes" if mode && kind && mode != kind
+
+      Protocol.validate_role!(role)
+      selected = mode || kind || :none
+      case selected
+      when :none then transport
+      when :http then HTTP.new(transport, role: role, host: host || "bing.com", uri: uri)
+      when :tls then TLS.new(transport, role: role, host: host || "cloudfront.net")
+      else raise ArgumentError, "unsupported obfuscation mode"
+      end
+    end
+
+    # 沿用底层传输的期限和所有权；每个方向在整个物理连接中
+    # 只发送或读取一次混淆握手。
+    class Wrapper
+      def initialize(transport, role:, host:)
+        unless host.is_a?(String) && !host.empty? && host.bytesize <= 255 && !host.match?(/[\r\n\0]/)
+          raise ArgumentError, "obfuscation host must contain 1..255 bytes without line breaks or NUL"
+        end
+
+        @transport = transport
+        @role = role
+        @host = host.b.freeze
+        @read_started = false
+        @write_started = false
+        @read_buffer = +"".b
+      end
+
+      def with_timeout(seconds, &)
+        @transport.with_timeout(seconds, &)
+      end
+
+      def close
+        @transport.close
+      end
+
+      def close_write
+        @transport.close_write
+      end
+
+      def closed?
+        @transport.closed?
+      end
+
+      def inspect
+        "#<#{self.class} role=#{@role}>"
+      end
+
+      private
+
+      def continuation(length)
+        return +"".b if length.zero?
+
+        @transport.read_exactly(length)
+      rescue EOFError
+        raise ProtocolError, "truncated obfuscation frame", cause: nil
+      end
+    end
+
+    # 有界的 HTTP 形态头部后直接传输 Snell 字节，不实现 WebSocket。
+    class HTTP < Wrapper
+      MAX_HEADER = 16 * 1024
+
+      def initialize(transport, role:, host:, uri:)
+        super(transport, role: role, host: host)
+        unless uri.is_a?(String) && uri.start_with?("/") && uri.bytesize <= 4096 && !uri.match?(/[\x00-\x20\x7f]/)
+          raise ArgumentError, "HTTP obfuscation URI must be an absolute path without whitespace or controls"
+        end
+
+        @uri = uri.b.freeze
+      end
+
+      def write_all(bytes)
+        raise ArgumentError, "payload must be a String" unless bytes.is_a?(String)
+        return 0 if bytes.empty?
+
+        wire = @write_started ? bytes : header(bytes.bytesize) + bytes.b
+        @write_started = true
+        @transport.write_all(wire)
+        bytes.bytesize
+      end
+
+      def read_exactly(length)
+        raise ArgumentError, "length must be nonnegative" unless length.is_a?(Integer) && length >= 0
+        return +"".b if length.zero?
+
+        read_header unless @read_started
+        @transport.read_exactly(length)
+      end
+
+      private
+
+      def header(length)
+        if @role == :client
+          "GET #{@uri} HTTP/1.1\r\nHost: #{@host}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" \
+          "Content-Length: #{length}\r\nSec-WebSocket-Key: #{[SecureRandom.random_bytes(16)].pack('m0')}\r\n\r\n".b
+        else
+          "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" \
+          "Sec-WebSocket-Accept: #{[SecureRandom.random_bytes(20)].pack('m0')}\r\n\r\n".b
+        end
+      end
+
+      def read_header
+        bytes = @transport.read_exactly(1)
+        until bytes.end_with?("\r\n\r\n")
+          raise ProtocolError, "HTTP obfuscation header exceeds limit" if bytes.bytesize >= MAX_HEADER
+
+          bytes << continuation(1)
+        end
+        @read_started = true
+      end
+    end
+
+    # 使用 TLS 形态记录传输字节，不提供 TLS 安全保证。
+    class TLS < Wrapper
+      MAX_RECORD = 16_384
+      MAX_EMPTY_RECORDS = 64
+      CIPHERS = [0xc02f, 0xc030, 0xcca8, 0xcca9, 0xc02b, 0xc02c, 0xc013, 0xc014,
+                 0xc009, 0xc00a, 0x009c, 0x009d, 0x002f, 0x0035, 0x003c, 0x003d,
+                 0x0067, 0x006b, 0x0033, 0x0039, 0x009e, 0x009f, 0xc027, 0xc028,
+                 0xc023, 0xc024, 0x00a2, 0x00a3].pack("n*").freeze
+
+      def write_all(bytes)
+        raise ArgumentError, "payload must be a String" unless bytes.is_a?(String)
+        return 0 if bytes.empty?
+
+        wire = +"".b
+        offset = 0
+        unless @write_started
+          length = [bytes.bytesize, @role == :client ? 1024 : MAX_RECORD].min
+          first = bytes.byteslice(0, length).b
+          wire << (@role == :client ? client_hello(first) : server_hello(first))
+          offset = length
+          @write_started = true
+        end
+        while offset < bytes.bytesize
+          length = [bytes.bytesize - offset, MAX_RECORD].min
+          wire << [23, 0x0303, length].pack("Cnn") << bytes.byteslice(offset, length).b
+          offset += length
+        end
+        @transport.write_all(wire)
+        bytes.bytesize
+      end
+
+      def read_exactly(length)
+        raise ArgumentError, "length must be nonnegative" unless length.is_a?(Integer) && length >= 0
+        return +"".b if length.zero?
+
+        empty_records = 0
+        while @read_buffer.bytesize < length
+          begin
+            part = @read_started ? read_frame : read_handshake
+          rescue EOFError
+            raise if @read_buffer.empty?
+
+            raise ProtocolError, "truncated obfuscation stream", cause: nil
+          end
+          if part.empty?
+            empty_records += 1
+            raise ProtocolError, "too many empty obfuscation frames" if empty_records > MAX_EMPTY_RECORDS
+          end
+          @read_buffer << part
+        end
+        result = @read_buffer.byteslice(0, length)
+        @read_buffer = @read_buffer.byteslice(length, @read_buffer.bytesize - length)
+        result
+      end
+
+      private
+
+      def client_hello(payload)
+        record_length = @host.bytesize + payload.bytesize + 212
+        hello = [22, 0x0301, record_length].pack("Cnn")
+        hello << "\x01".b << uint24(record_length - 4) << "\x03\x03".b
+        hello << SecureRandom.random_bytes(32) << "\x20".b << SecureRandom.random_bytes(32)
+        hello << [CIPHERS.bytesize].pack("n") << CIPHERS << "\x01\x00".b
+        hello << [@host.bytesize + payload.bytesize + 79, 35, payload.bytesize].pack("n*") << payload
+        hello << [0, @host.bytesize + 5, @host.bytesize + 3, 0, @host.bytesize].pack("nnnCn") << @host
+        hello << [10, 8, 6, 29, 23, 24].pack("n*")
+        hello << [13, 14, 12, 0x0403, 0x0503, 0x0603, 0x0401, 0x0501, 0x0601].pack("n*")
+        hello << ["000b0002010000170000ff0100010000150011"].pack("H*") << ("\0".b * 17)
+        hello
+      end
+
+      def server_hello(payload)
+        hello = [22, 0x0303, 70].pack("Cnn") + "\x02".b + uint24(66) + "\x03\x03".b
+        hello << SecureRandom.random_bytes(32) << "\x1a".b << SecureRandom.random_bytes(26)
+        hello << [0xc02f, 0, 0].pack("nCn")
+        hello << [20, 0x0303, 1, 1].pack("CnnC")
+        hello << [22, 0x0303, 16].pack("Cnn") << SecureRandom.random_bytes(16)
+        hello << [23, 0x0303, payload.bytesize].pack("Cnn") << payload
+      end
+
+      def uint24(number)
+        [number].pack("N").byteslice(1, 3)
+      end
+
+      def read_handshake
+        prefix_length = @role == :server ? 140 : 105
+        @transport.read_exactly(1)
+        continuation(prefix_length - 1)
+        length = continuation(2).unpack1("n")
+        limit = @role == :server ? 1024 : MAX_RECORD
+        raise ProtocolError, "oversized obfuscation handshake payload" if length > limit
+
+        payload = continuation(length)
+        if @role == :server
+          name_header = continuation(9)
+          name_length = name_header.byteslice(7, 2).unpack1("n")
+          raise ProtocolError, "oversized obfuscation hostname" if name_length > 255
+
+          continuation(name_length + 66)
+        end
+        @read_started = true
+        payload
+      end
+
+      def read_frame
+        first = @transport.read_exactly(1)
+        header = first + continuation(4)
+        type, version, length = header.unpack("Cnn")
+        unless type == 23 && version == 0x0303 && length <= MAX_RECORD
+          raise ProtocolError, "invalid obfuscation record header"
+        end
+
+        continuation(length)
+      end
+    end
+  end
+end

data/lib/snell/protocol.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Snell
+  # 请求、回复和 Snell UDP 载荷的纯编解码逻辑，不执行网络 I/O。
+  # 解码器区分非法协议数据与编码器调用参数错误。
+  module Protocol
+    COMMANDS = [0, 1, 5, 6].freeze
+    REPLIES = [0, 1, 2].freeze
+
+    # remaining 是提前发送的 TCP 数据，由 Server 解释与转发。
+    # 请求诊断不输出用户密钥或流量内容。
+    Request = Data.define(:command, :user_key, :destination, :remaining) do
+      def inspect
+        "#<#{self.class} command=#{command} destination=#{destination.inspect} remaining_bytes=#{remaining.bytesize}>"
+      end
+    end
+    Reply = Data.define(:kind, :code, :message, :payload)
+
+    module_function
+
+    def encode_request(command:, user_key: "", destination: nil)
+      raise ArgumentError, "unsupported command" unless COMMANDS.include?(command)
+
+      validate_bytes!(user_key, "user key", maximum: 255)
+      bytes = [1, command, user_key.bytesize].pack("C*") + user_key.b
+      if [1, 5].include?(command)
+        validate_address!(destination)
+        bytes << [destination.host.bytesize].pack("C") << destination.host << [destination.port].pack("n")
+      elsif destination
+        raise ArgumentError, "command does not accept a destination"
+      end
+      bytes
+    end
+
+    def decode_request(bytes)
+      cursor = Cursor.new(bytes)
+      raise ProtocolError, "unsupported request version" unless cursor.byte == 1
+
+      command = cursor.byte
+      raise ProtocolError, "unsupported request command" unless COMMANDS.include?(command)
+
+      user_key = cursor.take(cursor.byte).freeze
+      destination = [1, 5].include?(command) ? cursor.domain_address : nil
+      Request.new(command: command, user_key: user_key, destination: destination, remaining: cursor.rest.freeze)
+    end
+
+    def encode_reply(kind:, code: nil, message: nil, payload: "")
+      raise ArgumentError, "unsupported reply kind" unless REPLIES.include?(kind)
+
+      validate_bytes!(payload, "payload")
+      bytes = [kind].pack("C")
+      if kind == 2
+        raise ArgumentError, "error code must be a byte" unless code.is_a?(Integer) && code.between?(0, 255)
+
+        validate_bytes!(message, "error message", maximum: 255)
+        bytes << [code, message.bytesize].pack("CC") << message.b
+      elsif code || message
+        raise ArgumentError, "only error replies accept a code or message"
+      end
+      bytes << payload.b
+    end
+
+    def decode_reply(bytes)
+      cursor = Cursor.new(bytes)
+      kind = cursor.byte
+      raise ProtocolError, "unsupported reply kind" unless REPLIES.include?(kind)
+
+      code = kind == 2 ? cursor.byte : nil
+      message = kind == 2 ? cursor.take(cursor.byte).freeze : nil
+      Reply.new(kind: kind, code: code, message: message, payload: cursor.rest.freeze)
+    end
+
+    # encode_packet 的 role 表示发送方，decode_packet 的 role 表示接收方。
+    def encode_packet(payload, address, role:)
+      validate_role!(role)
+      validate_bytes!(payload, "payload")
+      validate_address!(address)
+      ip = address.ip
+      bytes = if role == :server
+                raise ArgumentError, "UDP source must be an IP address" unless ip
+
+                [ip.ipv4? ? 4 : 6].pack("C") + ip.hton
+              elsif ip
+                [1, 0, ip.ipv4? ? 4 : 6].pack("C*") + ip.hton
+              else
+                [1, address.host.bytesize].pack("CC") + address.host
+              end
+      bytes << [address.port].pack("n") << payload.b
+    end
+
+    def decode_packet(bytes, role:)
+      validate_role!(role)
+      cursor = Cursor.new(bytes)
+      if role == :server
+        raise ProtocolError, "unsupported UDP command" unless cursor.byte == 1
+
+        length = cursor.byte
+        address = length.zero? ? cursor.ip_address : cursor.domain_address(length)
+      else
+        address = cursor.ip_address
+      end
+      Datagram.new(payload: cursor.rest, address: address)
+    end
+
+    def validate_role!(role)
+      raise ArgumentError, "role must be :client or :server" unless %i[client server].include?(role)
+    end
+
+    def validate_address!(address)
+      raise ArgumentError, "destination must be a Snell::Address" unless address.is_a?(Address)
+    end
+
+    def validate_bytes!(bytes, name, maximum: nil)
+      raise ArgumentError, "#{name} must be a String" unless bytes.is_a?(String)
+      raise ArgumentError, "#{name} exceeds #{maximum} bytes" if maximum && bytes.bytesize > maximum
+    end
+
+    # 游标推进前先校验边界，截断输入不会产生不完整字段。
+    # 地址校验错误在此转换为协议异常。
+    class Cursor
+      def initialize(bytes)
+        raise ArgumentError, "wire data must be a String" unless bytes.is_a?(String)
+
+        @bytes = bytes.b
+        @offset = 0
+      end
+
+      def take(length)
+        raise ProtocolError, "truncated protocol message" if length > @bytes.bytesize - @offset
+
+        value = @bytes.byteslice(@offset, length)
+        @offset += length
+        value
+      end
+
+      def byte
+        take(1).getbyte(0)
+      end
+
+      def rest
+        take(@bytes.bytesize - @offset)
+      end
+
+      def domain_address(length = byte)
+        make_address(take(length), take(2).unpack1("n"))
+      end
+
+      def ip_address
+        family = byte
+        length = { 4 => 4, 6 => 16 }[family]
+        raise ProtocolError, "unsupported IP address family" unless length
+
+        make_address(IPAddr.new_ntoh(take(length)).to_s, take(2).unpack1("n"))
+      end
+
+      private
+
+      def make_address(host, port)
+        Address.new(host: host, port: port)
+      rescue ArgumentError
+        raise ProtocolError, "invalid protocol address", cause: nil
+      end
+    end
+    private_constant :Cursor
+  end
+end

data/lib/snell/record_reader.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "v6/profile"
+
+module Snell
+  # 一个物理连接的入站方向；逻辑 EOF 与顺序复用不重置
+  # 密码器或序列状态，上层必须串行化同方向的读取。
+  # 任何未完成或被拒绝的记录都会永久停用该读取器。
+  class RecordReader
+    attr_reader :salt
+    # 完整首条记录认证成功后才公开盐值；raw 模式没有认证盐值。
+    alias authenticated_salt salt
+
+    def initialize(transport, psk:, version:, role:, mode: :default)
+      validate_profile!(psk, version, mode, role)
+      @transport = transport
+      @psk = psk.b.freeze
+      @version = version
+      @mode = mode
+      @role = role
+      @cipher = nil
+      @salt = nil
+      @failed = false
+      @sequence = 0
+      @profile = V6::Profile.new(psk) if version == 6 && mode == :default
+    end
+
+    # 空载荷表示逻辑 EOF；记录开始前的物理 EOF 使用 EOFError。
+    # 记录开始后的截断使用 ProtocolError，不视为正常结束。
+    def read_record
+      completed = false
+      raise ProtocolError, "record reader is no longer usable" if @failed
+
+      first = @transport.read_exactly(1)
+      payload = read_started_record(first)
+      completed = true
+      payload
+    ensure
+      @failed = true unless completed
+    end
+
+    def inspect
+      "#<#{self.class} version=#{@version} mode=#{@mode} role=#{@role}>"
+    end
+
+    private
+
+    def read_started_record(first)
+      return read_shaped_record(first) if @profile
+
+      return decode_record(first + continuation(6), encrypted: false) if @mode == :raw
+
+      if @cipher
+        header = first + continuation(22)
+      else
+        candidate_salt = first + continuation(15)
+        @cipher = Crypto::Cipher.new(Crypto.derive_key(@psk, candidate_salt))
+        header = continuation(23)
+      end
+      payload = decode_record(@cipher.decrypt(header), encrypted: true)
+      @salt = candidate_salt.freeze if candidate_salt
+      payload
+    end
+
+    def read_shaped_record(first)
+      if @cipher
+        prefix = first + continuation(@profile.prefix_length(@sequence) - 1)
+      else
+        block = first + continuation(15 + @profile.salt_prefix_length)
+        candidate_salt = @profile.extract_salt(block)
+        @cipher = Crypto::Cipher.new(Crypto.derive_key(@psk, candidate_salt))
+        prefix = continuation(@profile.prefix_length(@sequence))
+      end
+      header = @cipher.decrypt(continuation(23), aad: prefix)
+      type, _reserved, padding_length, payload_length = header.unpack("Cnnn")
+      raise ProtocolError, "unsupported record type" unless type == 4
+
+      padding = continuation(padding_length)
+      payload = +"".b
+      if payload_length.positive?
+        payload = continuation(payload_length + Crypto::TAG_BYTES)
+        @profile.mix!(padding, payload, @sequence)
+        payload = @cipher.decrypt(payload, aad: padding)
+      end
+      @salt = candidate_salt.freeze if candidate_salt
+      @sequence = (@sequence + 1) & 0xffff_ffff
+      payload
+    end
+
+    def decode_record(header, encrypted:)
+      type, reserved, padding_length, payload_length = header.unpack("Cnnn")
+      raise ProtocolError, "unsupported record type" unless type == 4
+      if @version == 6 && (reserved.nonzero? || padding_length.nonzero?)
+        raise ProtocolError, "invalid version 6 record header"
+      end
+
+      # 旧版混合规则先从 padding 恢复被交换的密文字节，再验证标签。
+      # 该格式中未参与混合的 padding 不在认证范围内。
+      padding = continuation(padding_length)
+      return +"".b if payload_length.zero?
+
+      payload = continuation(payload_length + (encrypted ? Crypto::TAG_BYTES : 0))
+      return payload unless encrypted
+
+      [padding.bytesize, payload.bytesize].min.times do |index|
+        next if index.odd?
+
+        payload.setbyte(index, padding.getbyte(index))
+      end
+      @cipher.decrypt(payload)
+    end
+
+    def continuation(length)
+      return +"".b if length.zero?
+
+      @transport.read_exactly(length)
+    rescue EOFError
+      raise ProtocolError, "truncated record", cause: nil
+    end
+
+    def validate_profile!(psk, version, mode, role)
+      raise ArgumentError, "psk must be a nonempty String" unless psk.is_a?(String) && !psk.empty?
+      raise ArgumentError, "unsupported Snell version" unless [4, 5, 6].include?(version)
+      raise ArgumentError, "unsupported record mode" unless %i[default unshaped raw].include?(mode)
+      raise ArgumentError, "record mode requires version 6" if version != 6 && mode != :default
+      if version == 6 && !psk.bytesize.between?(12, 255)
+        raise ArgumentError, "version 6 psk must contain 12 to 255 bytes"
+      end
+
+      Protocol.validate_role!(role)
+    end
+  end
+end