localhost 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42bb902395ea685a7f1d14530439871920afb46b852aa9f6c3bbb8b66d07176a
-  data.tar.gz: 2b63d1af2999cd2ebca0f706bb626654cf765953fbbe1a0a6d4c3b6985482b50
+  metadata.gz: 2209cedcf5a6630d9733649ad2c73f1f8665034dc82374feab9087efcc34e7f1
+  data.tar.gz: bd7b98f6d5f3bfbe1a39e436de89679cd2eb8d6006c78bac03b1370ba3d45413
 SHA512:
-  metadata.gz: f27728bc1e1593af0db04c176bd99c878958aa662d6902649d6d5cb617034269e641a61d201255be7f8a859a08b3015980b56f28672dc301547f7aa3c6c96fa8
-  data.tar.gz: 66ad2882eef6927aaf6da87280931a81f5928d2cf72bb92a6a10451721465a08b9d51f52a01a1d97847a7019c634499c2cb068ed19401d1e8e713452ec633156
+  metadata.gz: dacfd029a503d102243431bc3f012d5a17b946f95ea78bcd3fa0dc9c61bcbfcaac62085e0046cf56f7a8ed92258c95e8130555a11bba69e8cdcd723283b70a49
+  data.tar.gz: ba94e80e5ffc354b0bfa55cb07aba0827a09ccfc339111c5210fa371d95aee44b3d1cc07663935c07b1e38271bb00732c9eb80b28c9124d3d1ac114f5d66fe55

data/lib/localhost/authority.rb

@@ -1,34 +1,32 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 # Copyright, 2019, by Richard S. Leung.
 # Copyright, 2021, by Akshay Birajdar.
 # Copyright, 2021, by Ye Lin Aung.
 # Copyright, 2023, by Antonio Terceiro.
 # Copyright, 2023, by Yuuji Yaginuma.
 # Copyright, 2024, by Colin Shea.
+# Copyright, 2024, by Aurel Branzeanu.
 
-require 'fileutils'
-require 'openssl'
+require "fileutils"
+require "openssl"
+
+require_relative "state"
+require_relative "issuer"
 
 module Localhost
 	# Represents a single public/private key pair for a given hostname.
 	class Authority
-		# Where to store the key pair on the filesystem. This is a subdirectory
-		# of $XDG_STATE_HOME, or ~/.local/state/ when that's not defined.
-		def self.path
-			File.expand_path("localhost.rb", ENV.fetch("XDG_STATE_HOME", "~/.local/state"))
-		end
-		
 		# List all certificate authorities in the given directory:
-		def self.list(root = self.path)
-			return to_enum(:list) unless block_given?
+		def self.list(path = State.path)
+			return to_enum(:list, path) unless block_given?
 			
-			Dir.glob("*.crt", base: root) do |path|
-				name = File.basename(path, ".crt")
+			Dir.glob("*.crt", base: path) do |certificate_path|
+				hostname = File.basename(certificate_path, ".crt")
 				
-				authority = self.new(name, root: root)
+				authority = self.new(hostname, path: path)
 				
 				if authority.load
 					yield authority
@@ -50,65 +48,73 @@ module Localhost
 		
 		# Create an authority forn the given hostname.
 		# @parameter hostname [String] The common name to use for the certificate.
-		# @parameter root [String] The root path for loading and saving the certificate.
-		def initialize(hostname = "localhost", root: self.class.path)
-			@root = root
+		# @parameter path [String] The path path for loading and saving the certificate.
+		def initialize(hostname = "localhost", path: State.path, issuer: Issuer.fetch)
+			@path = path
 			@hostname = hostname
+			@issuer = issuer
 			
+			@subject = nil
 			@key = nil
-			@name = nil
 			@certificate = nil
 			@store = nil
 		end
 		
+		attr :issuer
+		
 		# The hostname of the certificate authority.
 		attr :hostname
 		
 		BITS = 1024*2
 		
-		def ecdh_key
-			@ecdh_key ||= OpenSSL::PKey::EC.new "prime256v1"
-		end
-		
+		# @returns [OpenSSL::PKey::DH] A Diffie-Hellman key suitable for secure key exchange.
 		def dh_key
 			@dh_key ||= OpenSSL::PKey::DH.new(BITS)
 		end
 		
-		# The private key path.
+		# @returns [String] The path to the private key.
 		def key_path
-			File.join(@root, "#{@hostname}.key")
+			File.join(@path, "#{@hostname}.key")
 		end
 		
-		# The public certificate path.
+		# @returns [String] The path to the public certificate.
 		def certificate_path
-			File.join(@root, "#{@hostname}.crt")
+			File.join(@path, "#{@hostname}.crt")
 		end
 		
-		# The private key.
+		# @returns [OpenSSL::PKey::RSA] The private key.
 		def key
 			@key ||= OpenSSL::PKey::RSA.new(BITS)
 		end
 		
+		# Set the private key.
+		#
+		# @parameter key [OpenSSL::PKey::RSA] The private key.
 		def key= key
 			@key = key
 		end
 		
-		# The certificate name.
-		def name
-			@name ||= OpenSSL::X509::Name.parse("/O=Development/CN=#{@hostname}")
+		# @returns [OpenSSL::X509::Name] The subject name for the certificate.
+		def subject
+			@subject ||= OpenSSL::X509::Name.parse("/O=localhost.rb/CN=#{@hostname}")
 		end
 		
-		def name= name
-			@name = name
+		# Set the subject name for the certificate.
+		#
+		# @parameter subject [OpenSSL::X509::Name] The subject name.
+		def subject= subject
+			@subject = subject
 		end
 		
-		# The public certificate.
+		# Generates a self-signed certificate if one does not already exist for the given hostname.
+		# 
 		# @returns [OpenSSL::X509::Certificate] A self-signed certificate.
 		def certificate
+			issuer = @issuer || self
+			
 			@certificate ||= OpenSSL::X509::Certificate.new.tap do |certificate|
-				certificate.subject = self.name
-				# We use the same issuer as the subject, which makes this certificate self-signed:
-				certificate.issuer = self.name
+				certificate.subject = self.subject
+				certificate.issuer = issuer.subject
 				
 				certificate.public_key = self.key.public_key
 				
@@ -120,24 +126,27 @@ module Localhost
 				
 				extension_factory = OpenSSL::X509::ExtensionFactory.new
 				extension_factory.subject_certificate = certificate
-				extension_factory.issuer_certificate = certificate
-				
-				certificate.extensions = [
-					extension_factory.create_extension("basicConstraints", "CA:FALSE", true),
-					extension_factory.create_extension("subjectKeyIdentifier", "hash"),
-				]
+				extension_factory.issuer_certificate = @issuer&.certificate || certificate
 				
-				certificate.add_extension extension_factory.create_extension("authorityKeyIdentifier", "keyid:always,issuer:always")
+				certificate.add_extension extension_factory.create_extension("basicConstraints", "CA:FALSE", true)
+				certificate.add_extension extension_factory.create_extension("subjectKeyIdentifier", "hash")
 				certificate.add_extension extension_factory.create_extension("subjectAltName", "DNS: #{@hostname}")
+				certificate.add_extension extension_factory.create_extension("authorityKeyIdentifier", "keyid:always,issuer:always")
 				
-				certificate.sign self.key, OpenSSL::Digest::SHA256.new
+				certificate.sign issuer.key, OpenSSL::Digest::SHA256.new
 			end
 		end
 		
 		# The certificate store which is used for validating the server certificate.
+		#
+		# @returns [OpenSSL::X509::Store] The certificate store with the issuer certificate.
 		def store
 			@store ||= OpenSSL::X509::Store.new.tap do |store|
-				store.add_cert(self.certificate)
+				if @issuer
+					store.add_cert(@issuer.certificate)
+				else
+					store.add_cert(self.certificate)
+				end
 			end
 		end
 		
@@ -149,6 +158,10 @@ module Localhost
 				context.key = self.key
 				context.cert = self.certificate
 				
+				if @issuer
+					context.extra_chain_cert = [@issuer.certificate]
+				end
+				
 				context.session_id_context = "localhost"
 				
 				if context.respond_to? :tmp_dh_callback=
@@ -156,9 +169,7 @@ module Localhost
 				end
 				
 				if context.respond_to? :ecdh_curves=
-					context.ecdh_curves = 'P-256:P-384:P-521'
-				elsif context.respond_to? :tmp_ecdh_callback=
-					context.tmp_ecdh_callback = proc {self.ecdh_key}
+					context.ecdh_curves = "P-256:P-384:P-521"
 				end
 				
 				context.set_params(
@@ -179,12 +190,14 @@ module Localhost
 			end
 		end
 		
-		def load(path = @root)
-			ensure_authority_path_exists(path)
-			
+		# Load the certificate and key from the given path.
+		#
+		# @parameter path [String] The path to the certificate and key.
+		# @returns [Boolean] Whether the certificate and key were successfully loaded.
+		def load(path = @path)
 			certificate_path = File.join(path, "#{@hostname}.crt")
 			key_path = File.join(path, "#{@hostname}.key")
-						
+			
 			return false unless File.exist?(certificate_path) and File.exist?(key_path)
 			
 			certificate = OpenSSL::X509::Certificate.new(File.read(certificate_path))
@@ -199,9 +212,10 @@ module Localhost
 			return true
 		end
 		
-		def save(path = @root)
-			ensure_authority_path_exists(path)
-			
+		# Save the certificate and key to the given path.
+		#
+		# @parameter path [String] The path to save the certificate and key.
+		def save(path = @path)
 			lockfile_path = File.join(path, "#{@hostname}.lock")
 			
 			File.open(lockfile_path, File::RDWR|File::CREAT, 0644) do |lockfile|
@@ -217,20 +231,8 @@ module Localhost
 					self.key.to_pem
 				)
 			end
-		end
-		
-		# Ensures that the directory to store the certificate exists. If the legacy
-		# directory (~/.localhost/) exists, it is moved into the new XDG Basedir
-		# compliant directory.
-		def ensure_authority_path_exists(path = @root)
-			old_root = File.expand_path("~/.localhost")
 			
-			if File.directory?(old_root) and not File.directory?(path)
-				# Migrates the legacy dir ~/.localhost/ to the XDG compliant directory
-				File.rename(old_root, path)
-			elsif not File.directory?(path)
-				FileUtils.makedirs(path, mode: 0700)
-			end
+			return true
 		end
 	end
 end

data/lib/localhost/issuer.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "openssl"
+require "fileutils"
+
+require_relative "state"
+
+module Localhost
+	# Represents a local Root Certificate Authority used to sign development certificates.
+	class Issuer
+		# The default number of bits for the private key. 4096 bits.
+		BITS = 4096
+		
+		# The default validity period for the certificate. 10 years in seconds.
+		VALIDITY = 10 * 365 * 24 * 60 * 60
+		
+		# Fetch (load or create) a certificate issuer with the given name.
+		# See {#initialize} for the format of the arguments.
+		def self.fetch(*arguments, **options)
+			issuer = self.new(*arguments, **options)
+			
+			unless issuer.load
+				issuer.save
+			end
+			
+			return issuer
+		end
+		
+		# Initialize the issuer with the given name.
+		# 
+		# @parameter name [String] The common name to use for the certificate.
+		# @parameter path [String] The path path for loading and saving the certificate.
+		def initialize(name = "development", path: State.path)
+			@name = name
+			@path = path
+			
+			@subject = nil
+			@key = nil
+			@certificate = nil
+		end
+		
+		# @returns [String] The path to the private key.
+		def key_path
+			File.join(@path, "#{@name}.key")
+		end
+		
+		# @returns [String] The path to the public certificate.
+		def certificate_path
+			File.join(@path, "#{@name}.crt")
+		end
+		
+		# @returns [OpenSSL::X509::Name] The subject name for the certificate.
+		def subject
+			@subject ||= OpenSSL::X509::Name.parse("/O=localhost.rb/CN=#{@name}")
+		end
+		
+		# Set the subject name for the certificate.
+		#
+		# @parameter subject [OpenSSL::X509::Name] The subject name for the certificate.
+		def subject= subject
+			@subject = subject
+		end
+		
+		# @returns [OpenSSL::PKey::RSA] The private key.
+		def key
+			@key ||= OpenSSL::PKey::RSA.new(BITS)
+		end
+		
+		# The public certificate.
+		#
+		# @returns [OpenSSL::X509::Certificate] A self-signed certificate.
+		def certificate
+			@certificate ||= OpenSSL::X509::Certificate.new.tap do |certificate|
+				certificate.subject = self.subject
+				# We use the same issuer as the subject, which makes this certificate self-signed:
+				certificate.issuer = self.subject
+				
+				certificate.public_key = self.key.public_key
+				
+				certificate.serial = Time.now.to_i
+				certificate.version = 2
+				
+				certificate.not_before = Time.now - 10
+				certificate.not_after = Time.now + VALIDITY
+				
+				extension_factory = ::OpenSSL::X509::ExtensionFactory.new
+				extension_factory.subject_certificate = certificate
+				extension_factory.issuer_certificate = certificate
+				
+				certificate.add_extension extension_factory.create_extension("basicConstraints", "CA:TRUE", true)
+				certificate.add_extension extension_factory.create_extension("keyUsage", "keyCertSign, cRLSign", true)
+				certificate.add_extension extension_factory.create_extension("subjectKeyIdentifier", "hash")
+				certificate.add_extension extension_factory.create_extension("authorityKeyIdentifier", "keyid:always", false)
+				
+				certificate.sign self.key, OpenSSL::Digest::SHA256.new
+			end
+		end
+		
+		# Load the certificate and key from the given path.
+		#
+		# @parameter path [String] The path to load the certificate and key.
+		# @returns [Boolean] True if the certificate and key were loaded successfully.
+		def load(path = @root)
+			certificate_path = self.certificate_path
+			key_path = self.key_path
+			
+			return false unless File.exist?(certificate_path) and File.exist?(key_path)
+			
+			certificate = OpenSSL::X509::Certificate.new(File.read(certificate_path))
+			key = OpenSSL::PKey::RSA.new(File.read(key_path))
+			
+			@certificate = certificate
+			@key = key
+			
+			return true
+		end
+		
+		# @returns [String] The path to the lockfile.
+		def lockfile_path
+			File.join(@path, "#{@name}.lock")
+		end
+		
+		# Save the certificate and key to the given path.
+		#
+		# @parameter path [String] The path to save the certificate and key.
+		def save(path = @root)
+			lockfile_path = self.lockfile_path
+			
+			File.open(lockfile_path, File::RDWR|File::CREAT, 0644) do |lockfile|
+				lockfile.flock(File::LOCK_EX)
+				
+				File.write(
+					self.certificate_path,
+					self.certificate.to_pem
+				)
+				
+				File.write(
+					self.key_path,
+					self.key.to_pem
+				)
+			end
+			
+			return true
+		end
+	end
+end

data/lib/localhost/state.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "fileutils"
+
+module Localhost
+	# Represents a single public/private key pair for a given hostname.
+	module State
+		# Where to store the key pair on the filesystem. This is a subdirectory
+		# of $XDG_STATE_HOME, or ~/.local/state/ when that's not defined.
+		#
+		# Ensures that the directory to store the certificate exists. If the legacy
+		# directory (~/.localhost/) exists, it is moved into the new XDG Basedir
+		# compliant directory.
+		#
+		# @parameter env [Hash] The environment to use for configuration.
+		def self.path(env = ENV)
+			path = File.expand_path("localhost.rb", env.fetch("XDG_STATE_HOME", "~/.local/state"))
+			
+			unless File.directory?(path)
+				FileUtils.mkdir_p(path, mode: 0700)
+			end
+			
+			return path
+		end
+		
+		# Delete the directory where the key pair is stored.
+		#
+		# @parameter env [Hash] The environment to use for configuration.
+		def self.purge(env = ENV)
+			path = self.path(env)
+			
+			FileUtils.rm_rf(path)
+		end	
+	end
+end

data/lib/localhost/system/darwin.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Localhost
+	module System
+		module Darwin
+			def self.install(certificate)
+				login_keychain = File.expand_path("~/Library/Keychains/login.keychain-db")
+
+				system(
+					"security", "add-trusted-cert",
+					"-d", "-r", "trustRoot",
+					"-k", login_keychain,
+					certificate
+				)
+			end
+		end
+	end
+end

data/lib/localhost/system/linux.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "etc"
+
+module Localhost
+	module System
+		module Darwin
+			def self.install(certificate)
+				filename = File.basename(certificate)
+				destination = "/usr/local/share/ca-certificates/localhost-#{filename}"
+				
+				system("sudo", "cp", certificate, destination)
+				system("sudo", "update-ca-certificates")
+			end
+		end
+	end
+end

data/lib/localhost/system.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Localhost
+	module System
+		def self.current
+			case RUBY_PLATFORM
+			when /darwin/
+				require 'localhost/system/darwin'
+				Darwin
+			when /linux/
+				require 'localhost/system/linux'
+				Linux
+			else
+				raise NotImplementedError, "Unsupported platform: #{RUBY_PLATFORM}"
+			end
+		end
+	end
+end

data/lib/localhost/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2018-2024, by Samuel Williams.
 
 module Localhost
-	VERSION = "1.3.0"
+	VERSION = "1.4.0"
 end

data/lib/localhost.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
-require_relative 'localhost/version'
-require_relative 'localhost/authority'
+require_relative "localhost/version"
+require_relative "localhost/authority"
+require_relative "localhost/system"
+
+# @namespace
+module Localhost
+end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2018-2024, by Samuel Williams.  
+Copyright, 2018-2025, by Samuel Williams.  
 Copyright, 2018, by Gabriel Sobrinho.  
 Copyright, 2019, by Richard S. Leung.  
 Copyright, 2020-2021, by Olle Jonsson.  
@@ -10,6 +10,7 @@ Copyright, 2022, by Juri Hahn.
 Copyright, 2023, by Antonio Terceiro.  
 Copyright, 2023, by Yuuji Yaginuma.  
 Copyright, 2024, by Colin Shea.  
+Copyright, 2024, by Aurel Branzeanu.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -12,7 +12,27 @@ I wanted to provide a server-agnostic way of doing this, primarily because I thi
 
 ## Usage
 
-Please see the [project documentation](https://socketry.github.io/localhost/).
+Please see the [project documentation](https://socketry.github.io/localhost/) for more details.
+
+  - [Getting Started](https://socketry.github.io/localhost/guides/getting-started/index) - This guide explains how to use `localhost` for provisioning local TLS certificates for development.
+
+  - [Browser Configuration](https://socketry.github.io/localhost/guides/browser-configuration/index) - This guide explains how to configure your local browser in order to avoid warnings about insecure self-signed certificates.
+
+  - [Example Server](https://socketry.github.io/localhost/guides/example-server/index) - This guide demonstrates how to use <code class="language-ruby">Localhost::Authority</code> to implement a simple HTTPS client & server.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/localhost/releases/index) for all releases.
+
+### v1.4.0
+
+  - Add `localhost:purge` to delete all certificates.
+  - Add `localhost:install` to install the issuer certificate in the local trust store.
+
+## See Also
+
+  - [Falcon](https://github.com/socketry/falcon) — Uses `Localhost::Authority` to provide HTTP/2 with minimal configuration.
+  - [Puma](https://github.com/puma/puma) — Supports `Localhost::Authority` to provide self-signed HTTP for local development.
 
 ## Contributing
 
@@ -26,13 +46,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
-
-### Contributor Covenant
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+### Community Guidelines
 
-## See Also
-
-  - [Falcon](https://github.com/socketry/falcon) — Uses `Localhost::Authority` to provide HTTP/2 with minimal configuration.
-  - [Puma](https://github.com/puma/puma) — Supports `Localhost::Authority` to provide self-signed HTTP for local development.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## v1.4.0
+
+  - Add `localhost:purge` to delete all certificates.
+  - Add `localhost:install` to install the issuer certificate in the local trust store.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localhost
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -9,12 +9,12 @@ authors:
 - Ye Lin Aung
 - Akshay Birajdar
 - Antonio Terceiro
+- Aurel Branzeanu
 - Colin Shea
 - Gabriel Sobrinho
 - Juri Hahn
 - Richard S. Leung
 - Yuuji Yaginuma
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -46,26 +46,29 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-04-12 00:00:00.000000000 Z
+date: 2025-03-24 00:00:00.000000000 Z
 dependencies: []
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/localhost.rb
 - lib/localhost/authority.rb
+- lib/localhost/issuer.rb
+- lib/localhost/state.rb
+- lib/localhost/system.rb
+- lib/localhost/system/darwin.rb
+- lib/localhost/system/linux.rb
 - lib/localhost/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/localhost
 licenses:
 - MIT
 metadata:
   documentation_uri: https://socketry.github.io/localhost/
   source_code_uri: https://github.com/socketry/localhost.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -73,15 +76,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Manage a local certificate authority for self-signed localhost development
   servers.