io-endpoint 0.17.2 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af9622a36778938631f679dda8abc06668454c5693551761173757b2df01ec76
-  data.tar.gz: e3d58e00ad0e067628d53d7950fd4a801a588fe7935e53f74d0bdc3e5f810e8a
+  metadata.gz: 01c66c778ce2edc823029e630d48e6240d7540fc277604e47341fba40a2a0377
+  data.tar.gz: 4da0e58ab7270e0edde4442049dc6e6fc6a5b818798da77383c2e99ef6fa2cfe
 SHA512:
-  metadata.gz: a341c62ee7a064bc18cdecb7fcfc08cc40b2a9f863baf12b0423d8389af1c0cf90b21025d78b4dce04e7abe3007f2c32ef0e0bb6f46bc9cecaee620d1e29a967
-  data.tar.gz: f1abb49094a40133a3861d55a58be3efb2d868ad40cddf27b33a080e4596a872f422e7a2c70cca0ead57ebff47b193c5b823ef55c7cd8cac5fd5c855ae9749a1
+  metadata.gz: 2b1cf8108ad055f3e40ec41e4ee82d510c72d2ae17bd49bc895c4944ada35a9d1c45e97ea44aab6a7bc75d8bdc0f5c808009fe5012d843e6b591af1fdbef62e9
+  data.tar.gz: 0e0eee1759843f2c045be325730706ee85c730603172b76c252955bb2121f3c962bb4a60fbf6617e67d7ebc50ba83b0b3e304ba7d9d2c468c0fa77dd35b0bc46

data/context/getting-started.md

@@ -111,3 +111,37 @@ endpoint.connect do |socket|
 	puts response
 end
 ```
+
+### Configuring TLS Certificate Material
+
+Use {ruby IO::Endpoint::TLS::Configuration} to provide certificate and private key material without coupling application configuration to OpenSSL. Certificate material is supplied as PEM content rather than file paths, so it can be loaded from files, environment variables, or secret stores:
+
+```ruby
+trust_store = IO::Endpoint::TLS::TrustStore.parse(root_certificates)
+certificate_chain = IO::Endpoint::TLS::Certificates.parse(certificate_chain_bundle)
+
+tls_configuration = IO::Endpoint::TLS::Configuration.new(
+	trust_store: trust_store,
+	certificate_chain: certificate_chain,
+	private_key: private_key,
+)
+
+endpoint = IO::Endpoint.ssl(
+	"example.com",
+	443,
+	hostname: "example.com",
+	tls_configuration: tls_configuration,
+)
+```
+
+Use `TrustStore.new(certificates: certificates)` when certificates are already represented as an array of individual PEM strings. Use `TrustStore.parse(certificate_bundle)` to split a concatenated PEM bundle into that canonical representation, or `TrustStore.load("/path/to/certificates.pem")` to load and parse a bundle from a file. Options such as `system_certificates: true` are forwarded from `load` to `parse`.
+
+The local certificate chain is an ordered array of individual PEM strings, with the leaf certificate followed by any intermediate certificates. The root certificate is normally omitted. Use `Certificates.parse(certificate_bundle)` to split a concatenated bundle while preserving that order.
+
+Set `system_certificates: true` to include system-provided trusted certificates. System and custom certificates can be combined in the same trust store.
+
+The SSL endpoint converts the trust store into an OpenSSL certificate store and the complete configuration into an OpenSSL context. Other endpoint implementations can consume the same trust, identity, and verification configuration using their native TLS implementation.
+
+The OpenSSL conversion is also available directly using `IO::Endpoint::TLS::OpenSSL.build_certificate_store(trust_store)`.
+
+For a server which requires clients to provide a trusted certificate, set `verification: :required`. Use `:peer` to verify a certificate when the peer provides one, and `:none` to explicitly disable peer verification. When a trust store is supplied and no policy is specified, peer verification is enabled by default. On client connections with a hostname, peer verification also checks that the certificate identifies that hostname.

data/context/index.yaml

@@ -3,6 +3,8 @@
 ---
 description: Provides a separation of concerns interface for IO endpoints.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/io-endpoint/issues
+  changelog_uri: https://github.com/socketry/io-endpoint/blob/main/releases.md
   documentation_uri: https://socketry.github.io/io-endpoint
   source_code_uri: https://github.com/socketry/io-endpoint.git
 files:

data/lib/io/endpoint/ssl_endpoint.rb

@@ -5,6 +5,7 @@
 
 require_relative "host_endpoint"
 require_relative "generic"
+require_relative "tls/openssl"
 
 require "openssl"
 
@@ -22,77 +23,6 @@ module OpenSSL
 			end
 		end
 		
-		# Represents a module that forwards socket methods to the underlying IO object.
-		module SocketForwarder
-			unless method_defined?(:close_on_exec=)
-				# Set whether the socket should be closed on exec.
-				# @parameter value [Boolean] Whether to close on exec.
-				def close_on_exec=(value)
-					to_io.close_on_exec = value
-				end
-			end
-			
-			unless method_defined?(:local_address)
-				# Get the local address of the socket.
-				# @returns [Addrinfo] The local address.
-				def local_address
-					to_io.local_address
-				end
-			end
-			
-			unless method_defined?(:remote_address)
-				# Get the remote address of the socket.
-				# @returns [Addrinfo] The remote address.
-				def remote_address
-					to_io.remote_address
-				end
-			end
-			
-			unless method_defined?(:wait)
-				# Wait for the socket to become ready.
-				# @parameter arguments [Array] Arguments to pass to the underlying IO wait method.
-				# @returns [IO, nil] The socket if ready, nil otherwise.
-				def wait(*arguments)
-					to_io.wait(*arguments)
-				end
-			end
-			
-			unless method_defined?(:wait_readable)
-				# Wait for the socket to become readable.
-				# @parameter arguments [Array] Arguments to pass to the underlying IO wait_readable method.
-				# @returns [IO, nil] The socket if readable, nil otherwise.
-				def wait_readable(*arguments)
-					to_io.wait_readable(*arguments)
-				end
-			end
-			
-			unless method_defined?(:wait_writable)
-				# Wait for the socket to become writable.
-				# @parameter arguments [Array] Arguments to pass to the underlying IO wait_writable method.
-				# @returns [IO, nil] The socket if writable, nil otherwise.
-				def wait_writable(*arguments)
-					to_io.wait_writable(*arguments)
-				end
-			end
-			
-			if IO.method_defined?(:timeout)
-				unless method_defined?(:timeout)
-					# Get the timeout for socket operations.
-					# @returns [Numeric, nil] The timeout value.
-					def timeout
-						to_io.timeout
-					end
-				end
-				
-				unless method_defined?(:timeout=)
-					# Set the timeout for socket operations.
-					# @parameter value [Numeric, nil] The timeout value.
-					def timeout=(value)
-						to_io.timeout = value
-					end
-				end
-			end
-		end
 	end
 end
 
@@ -102,6 +32,7 @@ module IO::Endpoint
 		# Initialize a new SSL endpoint.
 		# @parameter endpoint [Generic] The underlying endpoint to wrap with SSL.
 		# @option ssl_context [OpenSSL::SSL::SSLContext, nil] An optional SSL context to use.
+		# @option tls_configuration [TLS::Configuration, nil] Transport-neutral TLS certificate and verification configuration.
 		# @parameter options [Hash] Additional options including `:ssl_params` and `:hostname`.
 		def initialize(endpoint, **options)
 			super(**options)
@@ -150,6 +81,12 @@ module IO::Endpoint
 			@options[:ssl_params]
 		end
 		
+		# Get the transport-neutral TLS configuration from options.
+		# @returns [TLS::Configuration, nil] The TLS configuration if specified.
+		def tls_configuration
+			@options[:tls_configuration]
+		end
+		
 		# Build an SSL context with configured parameters.
 		# @parameter context [OpenSSL::SSL::SSLContext] An optional SSL context to configure.
 		# @returns [OpenSSL::SSL::SSLContext] The configured SSL context.
@@ -158,6 +95,10 @@ module IO::Endpoint
 				context.set_params(params)
 			end
 			
+			if tls_configuration = self.tls_configuration
+				TLS::OpenSSL.apply(context, tls_configuration, hostname: self.hostname)
+			end
+			
 			# context.setup
 			# context.freeze
 			
@@ -246,11 +187,12 @@ module IO::Endpoint
 	
 	# @parameter arguments
 	# @parameter ssl_context [OpenSSL::SSL::SSLContext, nil]
+	# @parameter tls_configuration [TLS::Configuration, nil]
 	# @parameter hostname [String, nil]
 	# @parameter options keyword arguments passed through to {Endpoint.tcp}
 	#
 	# @returns [SSLEndpoint]
-	def self.ssl(*arguments, ssl_context: nil, hostname: nil, **options)
-		SSLEndpoint.new(self.tcp(*arguments, **options), ssl_context: ssl_context, hostname: hostname)
+	def self.ssl(*arguments, ssl_context: nil, tls_configuration: nil, hostname: nil, **options)
+		SSLEndpoint.new(self.tcp(*arguments, **options), ssl_context: ssl_context, tls_configuration: tls_configuration, hostname: hostname)
 	end
 end

data/lib/io/endpoint/tls/certificates.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module IO::Endpoint
+	# @namespace
+	module TLS
+		# Utilities for parsing PEM-encoded certificates.
+		module Certificates
+			# Matches individual certificates in a PEM bundle.
+			CERTIFICATE_PATTERN = /-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----/m
+			private_constant :CERTIFICATE_PATTERN
+			
+			# Parse a PEM-encoded certificate bundle into individual certificates.
+			# @parameter certificate_bundle [String] One or more certificates encoded as PEM.
+			# @returns [Array(String)] The individual PEM-encoded certificates in their original order.
+			# @raises [ArgumentError] If the bundle does not contain any certificates.
+			# @raises [TypeError] If the bundle is not a string.
+			def self.parse(certificate_bundle)
+				unless certificate_bundle.is_a?(String)
+					raise TypeError, "The certificate bundle must be provided as a string!"
+				end
+				
+				certificates = certificate_bundle.scan(CERTIFICATE_PATTERN)
+				
+				unless certificates.any?
+					raise ArgumentError, "The certificate bundle does not contain any certificates!"
+				end
+				
+				return certificates
+			end
+		end
+	end
+end

data/lib/io/endpoint/tls/configuration.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "trust_store"
+
+module IO::Endpoint
+	# @namespace
+	module TLS
+		# Represents transport-neutral TLS certificate and verification configuration.
+		class Configuration
+			# Initialize a TLS configuration from PEM-encoded certificate and private key material.
+			# @parameter trust_store [TrustStore | Nil] The trusted certificate sources.
+			# @parameter certificate_chain [Array(String) | Nil] The ordered local certificate chain encoded as individual PEM strings, with the leaf certificate followed by any intermediates.
+			# @parameter private_key [String | Nil] The private key encoded as PEM.
+			# @parameter verification [Symbol | Nil] The peer verification policy: `:none`, `:peer`, or `:required`. When omitted, `:peer` is used if a trust store is provided.
+			# @raises [ArgumentError] If the certificate chain and private key are not provided together, or the verification policy is invalid.
+			# @raises [TypeError] If the certificate chain or private key uses an unsupported representation.
+			def initialize(trust_store: nil, certificate_chain: nil, private_key: nil, verification: nil)
+				if certificate_chain
+					unless certificate_chain.is_a?(Array) && certificate_chain.all?{|certificate| certificate.is_a?(String)}
+						raise TypeError, "The certificate chain must be provided as an array of strings!"
+					end
+					
+					unless certificate_chain.any?
+						raise ArgumentError, "The certificate chain must contain at least one certificate!"
+					end
+				end
+				
+				unless private_key.nil? || private_key.is_a?(String)
+					raise TypeError, "The private key must be provided as a string!"
+				end
+				
+				if certificate_chain.nil? != private_key.nil?
+					raise ArgumentError, "The certificate chain and private key must be provided together!"
+				end
+				
+				verification = :peer if verification.nil? && trust_store
+				unless [nil, :none, :peer, :required].include?(verification)
+					raise ArgumentError, "Unsupported verification policy: #{verification.inspect}!"
+				end
+				
+				@trust_store = trust_store
+				@certificate_chain = certificate_chain
+				@private_key = private_key
+				@verification = verification
+			end
+			
+			# @attribute [TrustStore | Nil] The trusted certificate sources.
+			attr :trust_store
+			
+			# @attribute [Array(String) | Nil] The ordered local certificate chain encoded as individual PEM strings, with the leaf certificate followed by any intermediates.
+			attr :certificate_chain
+			
+			# @attribute [String | Nil] The private key encoded as PEM.
+			attr :private_key
+			
+			# @attribute [Symbol | Nil] The peer verification policy.
+			attr :verification
+			
+			# Whether peer certificates should be verified.
+			# @returns [Boolean] Whether peer verification is enabled.
+			def verify_peer?
+				return @verification == :peer || @verification == :required
+			end
+			
+			# Get a representation of the configuration without exposing certificate or private key material.
+			# @returns [String] A redacted representation of the configuration.
+			def inspect
+				attributes = {
+					trust_store: !@trust_store.nil?,
+					certificate_chain: !@certificate_chain.nil?,
+					private_key: !@private_key.nil?,
+					verification: @verification,
+				}
+				
+				return "\#<#{self.class} #{attributes.inspect}>"
+			end
+		end
+	end
+end

data/lib/io/endpoint/tls/openssl.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "trust_store"
+require_relative "configuration"
+
+require "openssl"
+
+module IO::Endpoint
+	module TLS
+		# Provides OpenSSL compilation for transport-neutral TLS configuration.
+		module OpenSSL
+			# Build an OpenSSL certificate store from transport-neutral trusted certificate configuration.
+			# @parameter trust_store [TrustStore] The trusted certificate sources.
+			# @returns [OpenSSL::X509::Store] The configured OpenSSL certificate store.
+			def self.build_certificate_store(trust_store)
+				::OpenSSL::X509::Store.new.tap do |store|
+					store.set_default_paths if trust_store.system_certificates?
+					
+					trust_store.certificates.each do |certificate_pem|
+						store.add_cert(::OpenSSL::X509::Certificate.new(certificate_pem))
+					end
+				end
+			end
+			
+			# Apply transport-neutral TLS configuration to an OpenSSL context.
+			# @parameter context [OpenSSL::SSL::SSLContext] The OpenSSL context to configure.
+			# @parameter configuration [Configuration] The transport-neutral TLS configuration.
+			# @parameter hostname [String | Nil] The hostname to verify for client connections.
+			# @returns [OpenSSL::SSL::SSLContext] The configured OpenSSL context.
+			def self.apply(context, configuration, hostname: nil)
+				if trust_store = configuration.trust_store
+					context.cert_store = build_certificate_store(trust_store)
+				end
+				
+				if certificate_chain = configuration.certificate_chain
+					certificates = certificate_chain.map do |certificate|
+						::OpenSSL::X509::Certificate.new(certificate)
+					end
+					
+					context.cert = certificates.shift
+					context.extra_chain_cert = certificates
+					context.key = ::OpenSSL::PKey.read(configuration.private_key)
+				end
+				
+				case configuration.verification
+				when :none
+					context.verify_mode = ::OpenSSL::SSL::VERIFY_NONE
+					context.verify_hostname = false
+				when :peer
+					context.verify_mode = ::OpenSSL::SSL::VERIFY_PEER
+				when :required
+					context.verify_mode = ::OpenSSL::SSL::VERIFY_PEER | ::OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT
+				end
+				
+				if hostname && configuration.verify_peer?
+					context.verify_hostname = true
+				end
+				
+				return context
+			end
+		end
+	end
+end

data/lib/io/endpoint/tls/trust_store.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "certificates"
+
+module IO::Endpoint
+	# @namespace
+	module TLS
+		# Represents transport-neutral trusted certificate sources.
+		class TrustStore
+			# Load a PEM-encoded certificate bundle from the given path.
+			# @parameter path [String | Interface(:to_path)] The path to the certificate bundle.
+			# @parameter options [Hash] Options forwarded to {.parse}.
+			# @returns [TrustStore] The loaded trust store.
+			def self.load(path, **options)
+				return parse(File.read(path), **options)
+			end
+			
+			# Parse a PEM-encoded certificate bundle into a trust store.
+			# @parameter certificate_bundle [String] One or more trusted certificates encoded as PEM.
+			# @parameter system_certificates [Boolean] Whether system-provided trusted certificates should be included.
+			# @returns [TrustStore] The parsed trust store.
+			# @raises [ArgumentError] If the bundle does not contain any certificates.
+			# @raises [TypeError] If the bundle is not a string.
+			def self.parse(certificate_bundle, system_certificates: false)
+				return self.new(certificates: Certificates.parse(certificate_bundle), system_certificates: system_certificates)
+			end
+			
+			# Initialize a trust store from PEM-encoded trusted certificates.
+			# @parameter certificates [Array(String)] The trusted certificates encoded as PEM.
+			# @parameter system_certificates [Boolean] Whether system-provided trusted certificates should be included.
+			# @raises [ArgumentError] If no source of trusted certificates is specified.
+			# @raises [TypeError] If certificates are not provided as strings.
+			def initialize(certificates: [], system_certificates: false)
+				unless certificates.is_a?(Array) && certificates.all?{|certificate| certificate.is_a?(String)}
+					raise TypeError, "Certificates must be provided as an array of strings!"
+				end
+				
+				unless certificates.any? || system_certificates
+					raise ArgumentError, "At least one source of trusted certificates must be specified!"
+				end
+				
+				@certificates = certificates
+				@system_certificates = system_certificates
+			end
+			
+			# @attribute [Array(String)] The individual trusted certificates encoded as PEM.
+			attr :certificates
+			
+			# Whether system-provided trusted certificates should be included.
+			# @returns [Boolean] `true` if system-provided trusted certificates should be included.
+			def system_certificates?
+				@system_certificates
+			end
+			
+			# Get a representation of the trust store without exposing certificate material.
+			# @returns [String] A redacted representation of the trust store.
+			def inspect
+				attributes = {
+					certificates: @certificates.size,
+					system_certificates: @system_certificates,
+				}
+				
+				return "\#<#{self.class} #{attributes.inspect}>"
+			end
+		end
+	end
+end

data/lib/io/endpoint/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Endpoint
-		VERSION = "0.17.2"
+		VERSION = "0.18.0"
 	end
 end

data/lib/io/endpoint.rb

@@ -6,6 +6,9 @@
 require_relative "endpoint/version"
 require_relative "endpoint/generic"
 require_relative "endpoint/shared_endpoint"
+require_relative "endpoint/tls/certificates"
+require_relative "endpoint/tls/trust_store"
+require_relative "endpoint/tls/configuration"
 
 # Represents a collection of endpoint classes for network I/O operations.
 module IO::Endpoint

data/readme.md

@@ -16,6 +16,12 @@ Please see the [project documentation](https://socketry.github.io/io-endpoint) f
 
 Please see the [project releases](https://socketry.github.io/io-endpointreleases/index) for all releases.
 
+### v0.18.0
+
+  - The `openssl` gem 3.3.0 or newer is now required.
+  - Added transport-neutral TLS trust stores, certificate chains and configuration, suitable for future QUIC integration.
+  - Added OpenSSL conversion and SSL endpoint integration, including hostname verification and mutual TLS.
+
 ### v0.17.2
 
   - When the unix path is bigger than what can fit into `struct sockaddr_un`, a shorter temporary path will be used instead and a symlink created at the original path.
@@ -54,10 +60,6 @@ Please see the [project releases](https://socketry.github.io/io-endpointreleases
 
   - Fixed state leak between iterations of the accept loop.
 
-### v0.13.0
-
-  - Propagate options assigned to composite endpoint to nested endpoints.
-
 ## See Also
 
   - [async-io](https://github.com/socketry/async-io) — Where this implementation originally came from.
@@ -66,11 +68,27 @@ Please see the [project releases](https://socketry.github.io/io-endpointreleases
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` bash
+$ bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
+```
 
 ### Developer Certificate of Origin
 

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.18.0
+
+  - The `openssl` gem 3.3.0 or newer is now required.
+  - Added transport-neutral TLS trust stores, certificate chains and configuration, suitable for future QUIC integration.
+  - Added OpenSSL conversion and SSL endpoint integration, including hostname verification and mutual TLS.
+
 ## v0.17.2
 
   - When the unix path is bigger than what can fit into `struct sockaddr_un`, a shorter temporary path will be used instead and a symlink created at the original path.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-endpoint
 version: !ruby/object:Gem::Version
-  version: 0.17.2
+  version: 0.18.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,7 +38,21 @@ cert_chain:
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.3.0
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -57,6 +71,10 @@ files:
 - lib/io/endpoint/shared_endpoint.rb
 - lib/io/endpoint/socket_endpoint.rb
 - lib/io/endpoint/ssl_endpoint.rb
+- lib/io/endpoint/tls/certificates.rb
+- lib/io/endpoint/tls/configuration.rb
+- lib/io/endpoint/tls/openssl.rb
+- lib/io/endpoint/tls/trust_store.rb
 - lib/io/endpoint/unix_endpoint.rb
 - lib/io/endpoint/version.rb
 - lib/io/endpoint/wrapper.rb
@@ -67,6 +85,8 @@ homepage: https://github.com/socketry/io-endpoint
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/io-endpoint/issues
+  changelog_uri: https://github.com/socketry/io-endpoint/blob/main/releases.md
   documentation_uri: https://socketry.github.io/io-endpoint
   source_code_uri: https://github.com/socketry/io-endpoint.git
 rdoc_options: []
@@ -76,14 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Provides a separation of concerns interface for IO endpoints.
 test_files: []