butler-http 0.1.0

data/lib/butler/connection_pool.rb

@@ -0,0 +1,64 @@
+# Unlike the Net::HTTP-based pool this replaces, Butler::ConnectionPool is
+# not a socket-level checkout/checkin pool — Async::HTTP::Client already
+# does per-origin pooling and HTTP/2 multiplexing internally (see
+# butler/transport.rb). This is a thin, bounded registry of one memoized
+# Butler::Connection per origin, so repeated requests to the same host
+# reuse the same underlying Async::HTTP::Client instead of rebuilding one
+# (and paying DNS/TCP/TLS setup again) on every call.
+class Butler::ConnectionPool
+  Entry = Struct.new(:connection, :last_used_at)
+
+  def initialize(config)
+    @config = config
+    @entries = {} # fingerprint => Entry, insertion-ordered (cheap LRU)
+    @mutex = Mutex.new
+  end
+
+  def acquire(uri, config)
+    key = fingerprint(uri, config)
+    now = monotonic_now
+
+    @mutex.synchronize do
+      if (entry = @entries.delete(key))
+        if now - entry.last_used_at <= config.pool.idle_timeout
+          entry.last_used_at = now
+          @entries[key] = entry # touch: move to the end
+          return entry.connection
+        else
+          entry.connection.close # sat idle past pool.idle_timeout — rebuild fresh below rather than reuse
+        end
+      end
+
+      connection = Butler::Transport.current.build_connection(uri, config)
+      @entries[key] = Entry.new(connection, now)
+      evict_if_needed!
+      connection
+    end
+  end
+
+  def reset!
+    @mutex.synchronize do
+      @entries.each_value { |entry| entry.connection.close }
+      @entries.clear
+    end
+  end
+
+  private
+
+  def fingerprint(uri, config)
+    transport_name = Butler::Transport.current.equal?(Butler::Testing::FakeTransport) ? "fake" : "real"
+    "#{uri.origin_key}|proxy=#{config.proxy}|http_version=#{config.http_version}|verify_tls=#{config.security.verify_tls}|transport=#{transport_name}"
+  end
+
+  def evict_if_needed!
+    max = @config.pool.max_connections
+    while @entries.size > max
+      _key, entry = @entries.shift
+      entry&.connection&.close
+    end
+  end
+
+  def monotonic_now
+    ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/butler/errors.rb

@@ -0,0 +1,78 @@
+# Butler's error hierarchy. Every error Butler itself raises is a
+# Butler::Errors::Error, so `rescue Butler::Errors::Error` is always a safe
+# top-level catch-all for "something about this HTTP call failed."
+#
+# The shape mirrors the PRD's proposed hierarchy closely, with two additions
+# not in that list: LimitExceeded (raised by Security::Limits, since response
+# and header size caps need somewhere to live) and TooManyRedirectsError
+# (carried over from the previous implementation).
+module Butler::Errors
+  class Error < StandardError; end
+
+  # The request was misconfigured (bad option, invalid combination) before
+  # anything was sent over the wire.
+  class ConfigurationError < Error; end
+
+  # The request itself couldn't be built/sent as specified.
+  class RequestError < Error; end
+
+  class TooManyRedirectsError < RequestError; end
+
+  # Something went wrong at or below the transport layer, i.e. the request
+  # never received a well-formed HTTP response.
+  class TransportError < Error; end
+  class ConnectionError < TransportError; end
+  class TimeoutError < TransportError; end
+  class TLSError < TransportError; end
+
+  # A TLSError specifically caused by certificate verification failing
+  # (self-signed, expired, hostname mismatch, untrusted root — anything
+  # OpenSSL itself reports as "certificate verify failed"). Split out from
+  # the general TLSError deliberately: unlike a transient TLS handshake
+  # failure, a bad certificate won't become valid on the very next retry a
+  # few hundred milliseconds later, so RetryPolicy excludes this subclass
+  # specifically while still retrying TLSError generally. Still a TLSError
+  # (rescue TLSError still catches it) — only its retry eligibility differs.
+  class CertificateVerificationError < TLSError; end
+
+  class DNSFailure < TransportError; end
+  class ProtocolError < TransportError; end
+
+  # A well-formed HTTP response was received. Only raised when a call is
+  # made with raise_on_error: true; carries the Butler::Response so rescuers
+  # can still inspect status/body/headers.
+  class HTTPError < Error
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super("#{response.status} response for #{response.uri}")
+    end
+  end
+
+  class ClientError < HTTPError; end
+  class ServerError < HTTPError; end
+
+  # Resilience-layer errors.
+  class RetryExhausted < Error
+    attr_reader :cause_response, :attempts
+
+    def initialize(message, cause_response: nil, attempts: nil)
+      @cause_response = cause_response
+      @attempts = attempts
+      super(message)
+    end
+  end
+
+  class CircuitOpen < Error; end
+  class Cancelled < Error; end
+
+  # Security::Limits (max_response_size / max_header_size). Not in the PRD's
+  # enumerated list, but there's nowhere else for this to live.
+  class LimitExceeded < Error; end
+
+  # HostPolicy allow/block list rejections. Kept as RequestError rather than
+  # a new subclass since "this request isn't allowed to be sent" is exactly
+  # what RequestError already means.
+  class HostNotAllowed < RequestError; end
+end

data/lib/butler/headers.rb

@@ -0,0 +1,106 @@
+# A case-insensitive, order-preserving, multi-value header map. Header
+# names are stored lower-cased internally (the shape both HTTP/2 and
+# Protocol::HTTP expect on the wire) but multiple values for the same name
+# (e.g. repeated Set-Cookie lines) are kept as separate pairs rather than
+# collapsed, since #[]= collapsing them would silently lose data on
+# responses.
+class Butler::Headers
+  include Enumerable
+
+  def initialize(pairs = nil)
+    @pairs = []
+    pairs&.each { |k, v| add(k, v) }
+  end
+
+  def self.from_a(pairs)
+    new(pairs)
+  end
+
+  # Accepts a Butler::Headers as-is, or builds one from a Hash/Array of pairs.
+  def self.coerce(headers)
+    return headers if headers.is_a?(Butler::Headers)
+
+    new(headers)
+  end
+
+  # First value for +key+ (the common case — most headers only ever appear
+  # once). Use #values_at to read every value of a repeated header.
+  def [](key)
+    dk = downcase(key)
+    pair = @pairs.find { |k, _| k == dk }
+    pair && pair[1]
+  end
+
+  # Replaces every existing value for +key+ with a single new one.
+  def []=(key, value)
+    delete(key)
+    add(key, value)
+  end
+
+  # Appends an additional value for +key+ without removing existing ones.
+  def add(key, value)
+    @pairs << [downcase(key), value.to_s]
+    value
+  end
+
+  def key?(key)
+    dk = downcase(key)
+    @pairs.any? { |k, _| k == dk }
+  end
+
+  def delete(key)
+    dk = downcase(key)
+    removed = @pairs.select { |k, _| k == dk }.map { |_, v| v }
+    @pairs.reject! { |k, _| k == dk }
+    removed.first
+  end
+
+  def values_at(key)
+    dk = downcase(key)
+    @pairs.select { |k, _| k == dk }.map { |_, v| v }
+  end
+
+  def each
+    return enum_for(:each) unless block_given?
+
+    @pairs.each { |k, v| yield k, v }
+  end
+
+  # Array of [lower-cased-name, value] pairs — exactly the shape
+  # Protocol::HTTP::Methods#get/post/... expects for its headers argument.
+  def to_a
+    @pairs.map(&:dup)
+  end
+
+  def to_h
+    @pairs.each_with_object({}) { |(k, v), h| h[k] = v }
+  end
+
+  # +other+'s keys replace this Headers' values for the same key (so
+  # per-request headers override client-level defaults, rather than
+  # duplicating them).
+  def merge(other)
+    merged = Butler::Headers.new(@pairs)
+    Butler::Headers.coerce(other).each { |k, v| merged[k] = v }
+    merged
+  end
+
+  def empty?
+    @pairs.empty?
+  end
+
+  def size
+    @pairs.size
+  end
+
+  def initialize_copy(source)
+    super
+    @pairs = @pairs.map(&:dup)
+  end
+
+  private
+
+  def downcase(key)
+    key.to_s.downcase
+  end
+end

data/lib/butler/pipeline/chain.rb

@@ -0,0 +1,18 @@
+class Butler
+  module Pipeline
+    # Builds the nested-proc chain out of an ordered list of middlewares
+    # plus a terminal step (ConnectionPool#acquire + Transport#call). Each
+    # middleware wraps the next, exactly like Rack.
+    class Chain
+      def initialize(middlewares, terminal:)
+        @app = middlewares.reverse.reduce(terminal) do |next_middleware, middleware|
+          ->(context) { middleware.call(context, next_middleware) }
+        end
+      end
+
+      def call(context)
+        @app.call(context)
+      end
+    end
+  end
+end

data/lib/butler/pipeline/context.rb

@@ -0,0 +1,21 @@
+class Butler
+  module Pipeline
+    # Carries everything one request attempt through the middleware chain
+    # needs. A fresh Context is built for every redirect hop (a new
+    # Butler::Request against the new URI), but shares the same Deadline
+    # across every hop and every retry attempt within a hop.
+    class Context
+      attr_accessor :client, :request, :response, :config, :deadline, :attempt, :metadata
+
+      def initialize(client:, request:, config:, deadline:)
+        @client = client
+        @request = request
+        @config = config
+        @deadline = deadline
+        @response = nil
+        @attempt = 0
+        @metadata = {}
+      end
+    end
+  end
+end

data/lib/butler/pipeline/middleware.rb

@@ -0,0 +1,16 @@
+class Butler
+  module Pipeline
+    # Documents the interface a pipeline middleware implements — not
+    # enforced through inheritance, just the shape every built-in
+    # middleware (and anything passed to Client#use) follows:
+    #
+    #   def call(context, next_middleware)
+    #     # ...inspect/modify context.request...
+    #     response = next_middleware.call(context)
+    #     # ...inspect/modify response, or handle an exception...
+    #     response
+    #   end
+    module Middleware
+    end
+  end
+end

data/lib/butler/pipeline/middlewares/circuit_breaker_middleware.rb

@@ -0,0 +1,21 @@
+class Butler
+  module Pipeline
+    module Middlewares
+      class CircuitBreakerMiddleware
+        def initialize(circuit_breaker)
+          @circuit_breaker = circuit_breaker
+        end
+
+        def call(context, next_middleware)
+          return next_middleware.call(context) unless context.config.circuit_breaker.enabled
+
+          scope_key = @circuit_breaker.scope_key_for(context.request, context.config)
+          @circuit_breaker.call(
+            scope_key, context.config.circuit_breaker,
+            failure: ->(response) { response.server_error? }
+          ) { next_middleware.call(context) }
+        end
+      end
+    end
+  end
+end

data/lib/butler/pipeline/middlewares/retry_middleware.rb

@@ -0,0 +1,67 @@
+class Butler
+  module Pipeline
+    module Middlewares
+      # The only middleware with a loop. Two independent retry paths — a
+      # raised transport-level exception, or a response whose status is
+      # retryable — each consulting Resilience::RetryPolicy for whether to
+      # retry and how long to wait first (see that class for the exact
+      # method/status/idempotency/deadline rules).
+      class RetryMiddleware
+        def initialize(retry_policy)
+          @retry_policy = retry_policy
+        end
+
+        def call(context, next_middleware)
+          attempt = 0
+
+          loop do
+            attempt += 1
+            context.attempt = attempt
+
+            begin
+              response = next_middleware.call(context)
+            rescue Butler::Errors::TransportError => e
+              retry_options = context.config.retry
+              if @retry_policy.retry_on_exception?(exception: e, attempt: attempt, deadline: context.deadline, retry_options: retry_options)
+                wait_before_retry(@retry_policy.delay_for(attempt: attempt, retry_options: retry_options, deadline: context.deadline))
+                next
+              end
+              raise wrap_exhausted(e, attempt, context.deadline)
+            end
+
+            retry_options = context.config.retry
+            if @retry_policy.retry_on_response?(request: context.request, response: response, attempt: attempt, deadline: context.deadline, retry_options: retry_options)
+              wait_before_retry(@retry_policy.delay_for(response: response, attempt: attempt, retry_options: retry_options, deadline: context.deadline))
+              next
+            end
+
+            return response
+          end
+        end
+
+        private
+
+        def wrap_exhausted(error, attempt, deadline)
+          return error if attempt <= 1
+
+          if deadline.expired?
+            Butler::Errors::TimeoutError.new("deadline exceeded after #{attempt} attempt(s): #{error.message}")
+          else
+            Butler::Errors::RetryExhausted.new("giving up after #{attempt} attempt(s): #{error.message}", attempts: attempt)
+          end
+        end
+
+        # Plain Kernel#sleep, not Async::Task#sleep (deprecated as of async
+        # 2.x): the `async` gem registers itself as a Fiber scheduler, so
+        # Kernel#sleep already yields to sibling fibers/tasks rather than
+        # blocking the thread whenever one is active — no need to reach for
+        # the task-specific API.
+        def wait_before_retry(seconds)
+          return if seconds <= 0
+
+          sleep(seconds)
+        end
+      end
+    end
+  end
+end

data/lib/butler/pipeline/middlewares/security_middleware.rb

@@ -0,0 +1,14 @@
+class Butler
+  module Pipeline
+    module Middlewares
+      # Runs first, before any socket is touched: rejects the request
+      # outright if its host isn't allowed (see Butler::Security::HostPolicy).
+      class SecurityMiddleware
+        def call(context, next_middleware)
+          Butler::Security::HostPolicy.check!(context.request.uri, context.config)
+          next_middleware.call(context)
+        end
+      end
+    end
+  end
+end

data/lib/butler/pipeline/middlewares/telemetry_middleware.rb

@@ -0,0 +1,37 @@
+class Butler
+  module Pipeline
+    module Middlewares
+      # Wraps the rest of the chain in Butler::Telemetry::Instrumentation
+      # (standalone pub/sub + optional ActiveSupport::Notifications bridge)
+      # and, when OpenTelemetry is loaded, a real tracing span with correct
+      # timing around the actual request execution. Its payload is built
+      # from an explicit allow-list of fields — it structurally never reads
+      # request/response bodies or Authorization/Cookie/Set-Cookie headers.
+      class TelemetryMiddleware
+        def call(context, next_middleware)
+          return next_middleware.call(context) unless context.config.telemetry.enabled
+
+          request = context.request
+          payload = { method: request.method, host: request.uri.host, port: request.uri.port, path: request.uri.uri.path }
+
+          Butler::Telemetry::Instrumentation.instrument(:request, payload) do
+            in_span(context.config, payload) do
+              response = next_middleware.call(context)
+              payload[:status] = response.status
+              payload[:attempt] = context.attempt
+              response
+            end
+          end
+        end
+
+        private
+
+        def in_span(config, payload, &block)
+          return block.call unless Butler::Telemetry::OpenTelemetryBridge.available?(config)
+
+          Butler::Telemetry::OpenTelemetryBridge.in_span(payload, &block)
+        end
+      end
+    end
+  end
+end

data/lib/butler/pipeline/middlewares/timeout_middleware.rb

@@ -0,0 +1,17 @@
+class Butler
+  module Pipeline
+    module Middlewares
+      # The total-budget checkpoint: raises before even attempting the next
+      # step once context.deadline has expired. Per-attempt connect/read/
+      # write timeouts are separate — those are handed to Async::HTTP as
+      # raw seconds and enforced by Butler::Resilience::Timeout inside
+      # Transport::Async.
+      class TimeoutMiddleware
+        def call(context, next_middleware)
+          context.deadline.exceeded!
+          next_middleware.call(context)
+        end
+      end
+    end
+  end
+end

data/lib/butler/quic/crypto/aead.rb

@@ -0,0 +1,69 @@
+class Butler
+  module Quic
+    module Crypto
+      # QUIC packet protection (RFC 9001 section 5.3): AEAD-encrypts a
+      # packet's payload with the unprotected header as associated data.
+      # The AEAD itself is OpenSSL's (AES-GCM / ChaCha20-Poly1305); this
+      # module only builds the nonce the spec describes and wires OpenSSL's
+      # streaming cipher API to it.
+      module AEAD
+        module_function
+
+        CIPHERS = {
+          aes_128_gcm: "aes-128-gcm",
+          aes_256_gcm: "aes-256-gcm",
+          chacha20_poly1305: "chacha20-poly1305",
+        }.freeze
+
+        TAG_LENGTH = 16
+
+        def seal(cipher_suite, key, nonce, plaintext, aad)
+          cipher = ::OpenSSL::Cipher.new(CIPHERS.fetch(cipher_suite))
+          cipher.encrypt
+          cipher.key = key
+          cipher.iv = nonce
+          cipher.auth_data = aad
+          ciphertext = cipher.update(plaintext) + cipher.final
+          ciphertext + cipher.auth_tag
+        end
+
+        # Raises Butler::Errors::TLSError (rather than letting the OpenSSL
+        # error leak) if the packet fails to authenticate — a forged or
+        # corrupted packet, or protection keys that don't actually match
+        # this packet. Also raised (not a raw ArgumentError/TypeError) if
+        # +ciphertext_and_tag+ is too short to even contain a tag — this is
+        # a public entry point that untrusted-length network data can reach
+        # directly, not just through Packet.unprotect's own length check.
+        def open(cipher_suite, key, nonce, ciphertext_and_tag, aad)
+          if ciphertext_and_tag.bytesize < TAG_LENGTH
+            raise Butler::Errors::TLSError, "QUIC packet too short (#{ciphertext_and_tag.bytesize} bytes) to contain an AEAD tag"
+          end
+
+          tag = ciphertext_and_tag.byteslice(-TAG_LENGTH, TAG_LENGTH)
+          ciphertext = ciphertext_and_tag.byteslice(0, ciphertext_and_tag.bytesize - TAG_LENGTH)
+
+          cipher = ::OpenSSL::Cipher.new(CIPHERS.fetch(cipher_suite))
+          cipher.decrypt
+          cipher.key = key
+          cipher.iv = nonce
+          cipher.auth_tag = tag
+          cipher.auth_data = aad
+          cipher.update(ciphertext) + cipher.final
+        rescue ::OpenSSL::Cipher::CipherError => e
+          raise Butler::Errors::TLSError, "QUIC packet failed to authenticate: #{e.message}"
+        end
+
+        # RFC 9001 section 5.3: the packet-protection nonce is the packet
+        # number, left-padded with zeros to the IV's length, XORed with the
+        # IV — built byte-by-byte rather than via Array#pack("Q>") since a
+        # QUIC packet number can in principle need up to 8 bytes and this
+        # keeps the padding/truncation behavior explicit either way.
+        def nonce_for(iv, packet_number)
+          pn_bytes = Array.new(iv.bytesize, 0)
+          iv.bytesize.times { |i| pn_bytes[iv.bytesize - 1 - i] = (packet_number >> (8 * i)) & 0xff }
+          iv.bytes.zip(pn_bytes).map { |a, b| a ^ b }.pack("C*")
+        end
+      end
+    end
+  end
+end

data/lib/butler/quic/crypto/header_protection.rb

@@ -0,0 +1,51 @@
+class Butler
+  module Quic
+    module Crypto
+      # QUIC header protection (RFC 9001 section 5.4): a 5-byte mask,
+      # derived from a 16-byte sample of the packet's own ciphertext, that
+      # XORs out the packet number's length bits and the packet number
+      # itself so on-path observers can't trivially correlate packet
+      # numbers across a connection. This is deliberately *not* an AEAD —
+      # it has no authentication of its own, which is why it's only ever
+      # applied on top of (never instead of) AEAD packet protection.
+      module HeaderProtection
+        module_function
+
+        SAMPLE_LENGTH = 16
+        MASK_LENGTH = 5
+
+        # RFC 9001 5.4.3 (AES-based suites) / 5.4.4 (ChaCha20-based suites).
+        def mask_for(cipher_suite, hp_key, sample)
+          if cipher_suite == :chacha20_poly1305
+            chacha20_mask(hp_key, sample)
+          else
+            aes_ecb_mask(hp_key, sample)
+          end
+        end
+
+        # RFC 9001 5.4.3: the mask is the sample AES-ECB-encrypted under the
+        # header-protection key — no IV, since ECB is only ever used here
+        # for this one fixed-size block, not as a general-purpose cipher.
+        def aes_ecb_mask(hp_key, sample)
+          cipher = ::OpenSSL::Cipher.new(hp_key.bytesize == 32 ? "aes-256-ecb" : "aes-128-ecb")
+          cipher.encrypt
+          cipher.key = hp_key
+          cipher.padding = 0
+          (cipher.update(sample) + cipher.final).byteslice(0, MASK_LENGTH)
+        end
+
+        # RFC 9001 5.4.4: the sample itself doubles as ChaCha20's 16-byte
+        # IV (a 4-byte little-endian counter followed by a 12-byte nonce —
+        # exactly the layout OpenSSL's raw "chacha20" cipher expects), used
+        # to encrypt 5 zero bytes.
+        def chacha20_mask(hp_key, sample)
+          cipher = ::OpenSSL::Cipher.new("chacha20")
+          cipher.encrypt
+          cipher.key = hp_key
+          cipher.iv = sample
+          cipher.update("\x00".b * MASK_LENGTH) + cipher.final
+        end
+      end
+    end
+  end
+end

data/lib/butler/quic/crypto/hkdf.rb

@@ -0,0 +1,44 @@
+class Butler
+  module Quic
+    module Crypto
+      # RFC 5869 HKDF, plus TLS 1.3's HKDF-Expand-Label construction (RFC
+      # 8446 section 7.1) that QUIC-TLS layers all of its key derivation on
+      # top of (RFC 9001 section 5). All actual cryptographic work (HMAC) is
+      # OpenSSL's — this module only assembles it into the shape the specs
+      # describe; it never implements a hash or cipher primitive itself.
+      module HKDF
+        module_function
+
+        def extract(salt, ikm, hash: "SHA256")
+          ::OpenSSL::HMAC.digest(hash, salt, ikm)
+        end
+
+        def expand(prk, info, length, hash: "SHA256")
+          hash_len = ::OpenSSL::Digest.new(hash).digest_length
+          blocks = (length.to_f / hash_len).ceil
+          raise ArgumentError, "length too large for HKDF-Expand" if blocks > 255
+
+          t = +""
+          okm = +""
+          (1..blocks).each do |i|
+            t = ::OpenSSL::HMAC.digest(hash, prk, t + info + [i].pack("C"))
+            okm << t
+          end
+          okm.byteslice(0, length)
+        end
+
+        # RFC 8446 section 7.1: HKDF-Expand-Label(Secret, Label, Context,
+        # Length). QUIC-TLS always uses the "tls13 " label prefix (RFC 9001
+        # section 5.1) and, for every secret Butler derives, an empty
+        # Context.
+        def expand_label(secret, label, length, context: "", hash: "SHA256")
+          full_label = "tls13 #{label}"
+          hkdf_label = [length].pack("n") <<
+                       [full_label.bytesize].pack("C") << full_label.b <<
+                       [context.bytesize].pack("C") << context.b
+          expand(secret, hkdf_label, length, hash: hash)
+        end
+      end
+    end
+  end
+end

data/lib/butler/quic/crypto/key_schedule.rb

@@ -0,0 +1,50 @@
+class Butler
+  module Quic
+    module Crypto
+      # QUIC-TLS key derivation for the Initial packet number space (RFC
+      # 9001 section 5.2). Initial secrets are derived from a fixed,
+      # version-specific public salt (not a real negotiated secret), so
+      # every QUIC v1 connection's Initial keys are public and the same
+      # derivation applies to every connection — which is exactly what lets
+      # RFC 9001 Appendix A publish literal test vectors for them.
+      #
+      # Handshake/1-RTT secrets (derived from the real TLS 1.3 handshake
+      # instead) are Stage 4+ work, not this module's.
+      module KeySchedule
+        module_function
+
+        # RFC 9001 section 5.2's QUIC v1 Initial salt.
+        INITIAL_SALT_V1 = ["38762cf7f55934b34d179ae6a4c80cadccbb7f0a"].pack("H*").freeze
+
+        KEY_LENGTHS = {
+          aes_128_gcm: 16,
+          aes_256_gcm: 32,
+          chacha20_poly1305: 32,
+        }.freeze
+
+        # Returns { client: client_initial_secret, server: server_initial_secret }
+        # for the given Destination Connection ID (the DCID the client chose
+        # for its first Initial packet).
+        def initial_secrets(destination_connection_id)
+          initial_secret = HKDF.extract(INITIAL_SALT_V1, destination_connection_id)
+          {
+            client: HKDF.expand_label(initial_secret, "client in", 32),
+            server: HKDF.expand_label(initial_secret, "server in", 32),
+          }
+        end
+
+        # RFC 9001 section 5.1: derives the AEAD key/iv and the
+        # header-protection key from a traffic secret, sized for
+        # +cipher_suite+.
+        def packet_protection_keys(secret, cipher_suite)
+          key_length = KEY_LENGTHS.fetch(cipher_suite)
+          {
+            key: HKDF.expand_label(secret, "quic key", key_length),
+            iv: HKDF.expand_label(secret, "quic iv", 12),
+            hp: HKDF.expand_label(secret, "quic hp", key_length),
+          }
+        end
+      end
+    end
+  end
+end