utopia 3.0.3 → 3.0.5

data/lib/utopia/exceptions/mailer.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2025, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 require "net/smtp"
 require "mail"
+require "console"
+require "stringio"
+require "yaml"
 
 require_relative "../middleware"
 require_relative "../request"
-require_relative "handler"
+require_relative "application_errors"
 
 module Utopia
 	module Exceptions
@@ -23,20 +26,33 @@ module Utopia
 			
 			DEFAULT_FROM = (ENV["USER"] || "utopia").freeze
 			DEFAULT_SUBJECT = "%{exception} [PID %{pid} : %{cwd}]".freeze
+			ATTACHMENT_SIZE_LIMIT = 64*1024
+			SENSITIVE_FIELD = /authorization|cookie|credential|password|private[_-]?key|referer|referrer|secret|session|token|variables|api[_-]?key/i
+			REDACTED = "[REDACTED]".freeze
 			
 			# @param to [String] The address to email error reports to.
 			# @param from [String] The from address for error reports.
 			# @param subject [String] The subject template which can access attributes defined by `#attributes_for`.
 			# @param delivery_method [Object] The delivery method as required by the mail gem.
-			# @param dump_environment [Boolean] Attach request attributes as `attributes.yaml` to the error report.
-			def initialize(app, to: "postmaster", from: DEFAULT_FROM, subject: DEFAULT_SUBJECT, delivery_method: LOCAL_SMTP, dump_environment: false)
+			# @param dump_body [Boolean] Attach a bounded rewindable request body to the error report.
+			# @param dump_environment [Boolean] Include application state and attach it as `state.yaml`.
+			# @param attachment_size_limit [Integer] The maximum size of each attachment.
+			# @param redact [Regexp | Nil] A pattern matching structured field names whose values should be redacted.
+			def initialize(app, to: "postmaster", from: DEFAULT_FROM, subject: DEFAULT_SUBJECT, delivery_method: LOCAL_SMTP, dump_body: false, dump_environment: false, attachment_size_limit: ATTACHMENT_SIZE_LIMIT, redact: SENSITIVE_FIELD)
 				super(app)
 				
 				@to = to
 				@from = from
 				@subject = subject
 				@delivery_method = delivery_method
+				@dump_body = dump_body
 				@dump_environment = dump_environment
+				@attachment_size_limit = Integer(attachment_size_limit)
+				@redact = redact
+				
+				if @attachment_size_limit < 0
+					raise ArgumentError, "attachment_size_limit must not be negative!"
+				end
 			end
 			
 			# Freeze this object and its internal state.
@@ -48,7 +64,10 @@ module Utopia
 				@from.freeze
 				@subject.freeze
 				@delivery_method.freeze
+				@dump_body.freeze
 				@dump_environment.freeze
+				@attachment_size_limit.freeze
+				@redact.freeze
 				
 				super
 			end
@@ -59,7 +78,7 @@ module Utopia
 			def call(request)
 				begin
 					return @delegate.call(request)
-				rescue => exception
+				rescue *APPLICATION_ERRORS => exception
 					request.exception = exception
 					send_notification exception, request
 					
@@ -99,30 +118,32 @@ module Utopia
 			def generate_body(exception, request)
 				io = StringIO.new
 				
-				io.puts "#{request.method} #{request.url}"
-				
-				# TODO embed the request body if it's textual?
-				# TODO dump and embed `utopia.variables`?
+				# Do not include the raw query string, as it may contain sensitive values:
+				io.puts "#{request.method} #{request.url.path.encoded}"
 				
 				io.puts
 				
 				REQUEST_ATTRIBUTES.each do |key|
-					value = request.send(key)
+					value = redact(key, request.send(key))
 					io.puts "request.#{key}: #{value.inspect}"
 				end
 				
 				request.query_parameters.each do |key, value|
+					value = redact(key, value)
 					io.puts "request.query_parameters.#{key}: #{value.inspect}"
 				end
 				
 				io.puts
 				
 				request.headers.each do |key, value|
+					value = redact(key, value)
 					io.puts "header[#{key.inspect}]: #{value.inspect}"
 				end
 				
-				self.current_state(request).each do |key, value|
-					io.puts "state.#{key}: #{value.inspect}"
+				if @dump_environment
+					filtered_state(request).each do |key, value|
+						io.puts "state.#{key}: #{value.inspect}"
+					end
 				end
 				
 				io.puts
@@ -150,12 +171,14 @@ module Utopia
 				mail.text_part = Mail::Part.new
 				mail.text_part.body = generate_body(exception, request)
 				
-				if body = extract_body(request) and body.size > 0
-					mail.attachments["body.bin"] = body
+				if @dump_body
+					if body = extract_body(request, @attachment_size_limit)
+						mail.attachments["body.bin"] = body
+					end
 				end
 				
 				if @dump_environment
-					mail.attachments["state.yaml"] = YAML.dump(self.current_state(request))
+					attach(mail, "state.yaml", YAML.dump(filtered_state(request)))
 				end
 				
 				return mail
@@ -168,8 +191,7 @@ module Utopia
 				
 				mail.deliver
 			rescue => mail_exception
-				$stderr.puts mail_exception.to_s
-				$stderr.puts mail_exception.backtrace
+				Console.warn(self, "Failed to deliver exception notification.", error: mail_exception)
 			end
 			
 			def current_state(request)
@@ -181,11 +203,51 @@ module Utopia
 				}
 			end
 			
-			def extract_body(request)
+			def filtered_state(request)
+				redact(nil, current_state(request))
+			end
+			
+			def redact(name, value)
+				if @redact && name
+					if @redact.match?(name.to_s)
+						return REDACTED
+					end
+				end
+				
+				case value
+				when Hash
+					return value.to_h do |key, item|
+						[key, redact(key, item)]
+					end
+				when Array
+					return value.map{|item| redact(nil, item)}
+				else
+					return value
+				end
+			end
+			
+			def attach(mail, name, content)
+				if content.bytesize <= @attachment_size_limit
+					mail.attachments[name] = content
+				end
+			end
+			
+			def extract_body(request, size_limit)
 				body = request.body
 				
 				if body&.rewindable? && body.rewind
-					return body.join
+					buffer = String.new.b
+					
+					body.each do |chunk|
+						# Do not retain a partial body when the complete attachment would exceed the limit:
+						if chunk.bytesize > size_limit - buffer.bytesize
+							return nil
+						end
+						
+						buffer << chunk
+					end
+					
+					return buffer unless buffer.empty?
 				end
 			end
 		end

data/lib/utopia/path.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2009-2026, by Samuel Williams.
 
 require "protocol/url/path"
 
 module Utopia
-	# Represents a path as an array of path components. Useful for efficient URL manipulation.
+	# Represents an application path as a traversal through a tree.
+	#
+	# Each component names a node and `/` represents the edge between adjacent nodes. A leading empty component anchors the traversal at the root, while a trailing empty component preserves an explicit final edge and denotes a directory:
+	#
+	# - `["foo", "bar"]` represents `foo/bar`.
+	# - `["", "foo", "bar"]` represents `/foo/bar`.
+	# - `["", "foo", "bar", ""]` represents `/foo/bar/`.
+	#
+	# The structural root is represented by `[""]` and contains no traversed edge. It is intentionally distinct from parsing `/`, which preserves the explicit edge as `["", ""]`. Both serialize as `/`, but they retain different structural representations. In particular, the structural root maps to an empty local path so it can be resolved relative to an application root.
 	class Path
 		include Comparable
 		
@@ -36,7 +44,7 @@ module Utopia
 			@components.empty?
 		end
 		
-		# Construct the root path.
+		# Construct the structural root path without an explicit trailing separator.
 		# @returns [Path] The root path.
 		def self.root
 			self.new([""])
@@ -203,12 +211,6 @@ module Utopia
 			end
 		end
 		
-		# Remove the first component when this path is relative.
-		# @returns [String | Nil] The removed component, or `nil` when the path is absolute.
-		def to_relative!
-			@components.shift if relative?
-		end
-		
 		# Convert this object to a string.
 		# @returns [String] The resulting string.
 		def to_str
@@ -532,11 +534,4 @@ module Utopia
 			return index
 		end
 	end
-	
-	# Coerce a value into a {Path}.
-	# @parameter path [Utopia::Path | String] The path.
-	# @returns [Path | Nil] The coerced path.
-	def self.Path(path)
-		Path.create(path)
-	end
 end

data/lib/utopia/request.rb

@@ -117,28 +117,13 @@ module Utopia
 			@query_parameters ||= parse_query_parameters(self.url.query)
 		end
 		
-		private def parse_cookies(cookie_header)
-			cookies = {}
-			
-			return cookies unless cookie_header
-			
-			if cookie_header.respond_to?(:to_str)
-				cookie_header = cookie_header.to_str
-			else
-				cookie_header = cookie_header.to_s
-			end
-			
-			cookie_header.split(/;\s*/).each do |pair|
-				key, value = pair.split("=", 2)
-				cookies[key] = value || ""
-			end
-			
-			return cookies
-		end
-		
 		# Decoded request cookies.
 		def cookies
-			@cookies ||= parse_cookies(self.headers["cookie"])
+			@cookies ||= if cookie_header = self.headers["cookie"]
+				cookie_header.to_h.transform_values(&:value)
+			else
+				{}
+			end
 		end
 		
 		# The request user agent.

data/lib/utopia/session/lazy_hash.rb

@@ -16,10 +16,6 @@ module Utopia
 				@loader = block
 			end
 			
-			# The loaded session values, if already loaded.
-			# @returns [Hash | Nil] The loaded values.
-			attr :values
-			
 			# Fetch a value by key, loading the hash if necessary.
 			# @parameter key [Object] The key.
 			# @returns [Object | Nil] The value.
@@ -66,10 +62,26 @@ module Utopia
 				@changed
 			end
 			
-			# Load and return the underlying values.
-			# @returns [Hash] The loaded values.
-			def load!
-				@values ||= @loader.call
+			# The current time for session expiry and persistence.
+			# @returns [Time] The current time in UTC.
+			def now
+				Time.now.utc
+			end
+			
+			# Persist the session values if they have changed or require updating.
+			# @parameter timeout [Numeric | Nil] The maximum age before an update is required.
+			# @yields {|values, updated_at| ...} The loaded values and their update time.
+			# @returns [Object | Nil] The result of the block if persistence was required.
+			def persist(timeout = nil)
+				return unless needs_update?(timeout)
+				
+				values = load!
+				updated_at = values[:updated_at] = now
+				
+				result = yield(values, updated_at)
+				@changed = false
+				
+				return result
 			end
 			
 			# Check whether the underlying values have been loaded.
@@ -88,11 +100,18 @@ module Utopia
 				# We want to be careful here and not call load! which isn't cheap operation.
 				if timeout and @values and updated_at = @values[:updated_at]
 					# If the last update was too long ago, we need update:
-					return true if updated_at < (Time.now - timeout)
+					return true if updated_at < (now - timeout)
 				end
 				
 				return false
 			end
+			
+			private
+			
+			# Load and return the underlying values.
+			def load!
+				@values ||= @loader.call(now)
+			end
 		end
 	end
 end

data/lib/utopia/session/middleware.rb

@@ -24,12 +24,14 @@ module Utopia
 			class PayloadError < StandardError
 			end
 			
-			MAXIMUM_SIZE = 1024*32
+			SIZE_LIMIT = 1024*32
 			
 			SECRET_KEY = "UTOPIA_SESSION_SECRET".freeze
 			
 			SESSION_KEY = "utopia.session".freeze
-			CIPHER_ALGORITHM = "aes-256-cbc"
+			CIPHER_ALGORITHM = "aes-256-gcm"
+			PAYLOAD_VERSION = "v1".freeze
+			AUTHENTICATION_TAG_SIZE = 16
 			
 			# The session will expire if no requests were made within 24 hours:
 			DEFAULT_EXPIRES_AFTER = 3600*24
@@ -48,8 +50,8 @@ module Utopia
 			# @param http_only [Boolean] Whether client-side scripts may access the cookie.
 			# @param same_site [Symbol | String | Boolean | Nil] Controls whether the cookie is sent with cross-site requests.
 			# @param partitioned [Boolean] Whether the cookie uses partitioned storage.
-			# @param maximum_size [Integer | Nil] The maximum encoded session payload size.
-			def initialize(app, session_name: SESSION_KEY, secret: nil, expires_after: DEFAULT_EXPIRES_AFTER, update_timeout: DEFAULT_UPDATE_TIMEOUT, domain: nil, path: "/", max_age: nil, secure: false, http_only: true, same_site: :lax, partitioned: false, maximum_size: MAXIMUM_SIZE)
+			# @param size_limit [Integer | Nil] The encoded session payload size limit.
+			def initialize(app, session_name: SESSION_KEY, secret: nil, expires_after: DEFAULT_EXPIRES_AFTER, update_timeout: DEFAULT_UPDATE_TIMEOUT, domain: nil, path: "/", max_age: nil, secure: false, http_only: true, same_site: :lax, partitioned: false, size_limit: SIZE_LIMIT)
 				super(app)
 				
 				@session_name = session_name
@@ -61,6 +63,7 @@ module Utopia
 				
 				# This generates a 32-byte key suitable for aes.
 				@key = Digest::SHA2.digest(secret)
+				@authentication_context = "#{@cookie_name}\0#{PAYLOAD_VERSION}".b.freeze
 				
 				@expires_after = expires_after
 				@update_timeout = update_timeout
@@ -82,7 +85,7 @@ module Utopia
 				}
 				
 				@serialization = Serialization.new
-				@maximum_size = maximum_size
+				@size_limit = size_limit
 			end
 			
 			attr :cookie_name
@@ -100,6 +103,7 @@ module Utopia
 				
 				@cookie_name.freeze
 				@key.freeze
+				@authentication_context.freeze
 				@expires_after.freeze
 				@update_timeout.freeze
 				@cookie_defaults.freeze
@@ -139,59 +143,53 @@ module Utopia
 			end
 			
 			def prepare_session(request)
-				LazyHash.new do
-					self.load_session_values(request)
+				LazyHash.new do |now|
+					self.load_session_values(request, now)
 				end
 			end
 			
 			def update_session(session_hash, headers)
-				if session_hash.needs_update?(@update_timeout)
-					values = session_hash.values
-					
-					values[:updated_at] = Time.now.utc
-					
-					data = encrypt(session_hash.values)
-					
-					commit(data, values[:updated_at], headers)
+				session_hash.persist(@update_timeout) do |values, updated_at|
+					commit(encrypt(values), updated_at, headers)
 				end
 			end
 			
 			# Constructs a valid session for the given request. These fields must match as per the checks performed in `valid_session?`:
-			def build_initial_session(request)
+			def build_initial_session(request, now)
 				{
 					user_agent: request.user_agent,
-					created_at: Time.now.utc,
-					updated_at: Time.now.utc,
+					created_at: now,
+					updated_at: now,
 				}
 			end
 			
 			# Load session from user supplied cookie. If the data is invalid or otherwise fails validation, `build_iniital_session` is invoked.
 			# @return hash of values.
-			def load_session_values(request)
+			def load_session_values(request, now)
 				# Decrypt the data from the user if possible:
 				if data = request.cookies[@cookie_name]
 					begin
 						if values = decrypt(data)
-							validate_session!(request, values)
+							validate_session!(request, values, now)
 							
 							return values
 						end
-					rescue => error
-						Console.error(self, error)
+					rescue PayloadError => error
+						Console.debug(self, "Discarding invalid session cookie!", exception: error)
 					end
 				end
 				
 				# If we couldn't create a session
-				return build_initial_session(request)
+				return build_initial_session(request, now)
 			end
 			
-			def validate_session!(request, values)
+			def validate_session!(request, values, now)
 				if values[:user_agent] != request.user_agent
 					raise PayloadError, "Invalid session because supplied user agent #{request.user_agent.inspect} does not match session user agent #{values[:user_agent].inspect}!"
 				end
 				
 				if expires_at = expires(values[:updated_at])
-					if expires_at < Time.now.utc
+					if expires_at < now
 						raise PayloadError, "Expired session cookie, user agent submitted a cookie that should have expired at #{expires_at}."
 					end
 				end
@@ -199,7 +197,7 @@ module Utopia
 				return true
 			end
 			
-			def expires(updated_at=Time.now.utc)
+			def expires(updated_at)
 				if @expires_after
 					return updated_at + @expires_after
 				end
@@ -253,38 +251,65 @@ module Utopia
 			end
 			
 			def encrypt(hash)
-				c = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
-				c.encrypt
+				cipher = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
+				cipher.encrypt
+				
+				cipher.key = @key
+				cipher.iv = initialization_vector = cipher.random_iv
+				cipher.auth_data = @authentication_context
+				
+				encrypted_data = cipher.update(@serialization.dump(hash))
+				encrypted_data << cipher.final
 				
-				# your pass is what is used to encrypt/decrypt
-				c.key = @key
-				c.iv = iv = c.random_iv
+				payload = initialization_vector + encrypted_data + cipher.auth_tag(AUTHENTICATION_TAG_SIZE)
+				data = "#{PAYLOAD_VERSION}.#{[payload].pack("m0")}"
 				
-				e = c.update(@serialization.dump(hash))
-				e << c.final
+				validate_size!(data)
 				
-				return [iv + e].pack("m0")
+				return data
 			end
 			
 			def decrypt(data)
-				if @maximum_size and data.bytesize > @maximum_size
-					raise PayloadError, "Session payload size #{data.bytesize}bytes exceeds maximum allowed size #{@maximum_size}bytes!"
-				end
-				
-				payload = data.unpack1("m0")
-				iv = payload.byteslice(0, 16)
-				e = payload.byteslice(16..)
-				
-				c = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
-				c.decrypt
+				validate_size!(data)
 				
-				c.key = @key
-				c.iv = iv
+				version, encoded_payload = data.split(".", 2)
 				
-				d = c.update(e)
-				d << c.final
+				if version != PAYLOAD_VERSION or encoded_payload.nil?
+					raise PayloadError, "Unsupported session payload format!"
+				end
 				
-				return @serialization.load(d)
+				begin
+					cipher = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
+					payload = encoded_payload.unpack1("m0")
+					minimum_size = cipher.iv_len + AUTHENTICATION_TAG_SIZE
+					
+					if payload.bytesize < minimum_size
+						raise PayloadError, "Invalid session payload!"
+					end
+					
+					initialization_vector = payload.byteslice(0, cipher.iv_len)
+					encrypted_data = payload.byteslice(cipher.iv_len, payload.bytesize - minimum_size)
+					authentication_tag = payload.byteslice(-AUTHENTICATION_TAG_SIZE, AUTHENTICATION_TAG_SIZE)
+					
+					cipher.decrypt
+					cipher.key = @key
+					cipher.iv = initialization_vector
+					cipher.auth_tag = authentication_tag
+					cipher.auth_data = @authentication_context
+					
+					decrypted_data = cipher.update(encrypted_data)
+					decrypted_data << cipher.final
+					
+					return @serialization.load(decrypted_data)
+				rescue ArgumentError, OpenSSL::Cipher::CipherError
+					raise PayloadError, "Invalid session payload!"
+				end
+			end
+			
+			def validate_size!(data)
+				if @size_limit and data.bytesize > @size_limit
+					raise PayloadError, "Session payload size #{data.bytesize}bytes exceeds size limit #{@size_limit}bytes!"
+				end
 			end
 		end
 	end

data/lib/utopia/static/local_file.rb

@@ -69,9 +69,13 @@ module Utopia
 				ranges = byte_ranges(request)
 				size = bytesize
 				
-				# puts "Requesting ranges: #{ranges.inspect} (#{size})"
-				
-				if ranges == nil or ranges.size != 1
+				# A valid byte-range request with no satisfiable ranges cannot be fulfilled:
+				if ranges && ranges.empty?
+					response_headers[CONTENT_LENGTH] = "0"
+					response_headers[CONTENT_RANGE] = "bytes */#{size}"
+					
+					return Response[416, response_headers, []]
+				elsif ranges == nil or ranges.size != 1
 					# No ranges, or multiple ranges (which we don't support).
 					# TODO: Support multiple byte-ranges, for now just send entire file:
 					status = 200

data/lib/utopia/static/middleware.rb

@@ -11,8 +11,6 @@ require_relative "local_file"
 require_relative "mime_types"
 require_relative "../localization/resolver"
 
-require "traces/provider"
-
 module Utopia
 	module Static
 		DEFAULT_CACHE_CONTROL = "public, max-age=3600".freeze
@@ -138,15 +136,5 @@ module Utopia
 			end
 		end
 		
-		Traces::Provider(Static) do
-			def respond(request, path, extension, content_type, localization: request.localization)
-				attributes = {
-					path: path,
-					locale: localization&.locale,
-				}
-				
-				Traces.trace("utopia.static.respond", attributes: attributes){super}
-			end
-		end
 	end
 end

data/lib/utopia/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Utopia
-	VERSION = "3.0.3"
+	VERSION = "3.0.5"
 end

data/readme.md

@@ -31,6 +31,15 @@ Please see the [project documentation](https://socketry.github.io/utopia/) for m
 
 Please see the [project releases](https://socketry.github.io/utopia/releases/index) for all releases.
 
+### v3.0.5
+
+  - **Breaking** Remove support for JavaScript packages installed in `lib/components`; use `node_modules` instead.
+  - **Breaking** Expose <code class="language-ruby">Utopia::Content::Middleware\#links</code> as the content link resolver rather than an indexed lookup method.
+  - **Security** Authenticate encrypted session cookies using AES-256-GCM. Existing session cookies are invalidated.
+  - Constrain content node local paths to the configured content root.
+  - **Security** Redact sensitive exception report fields and make bounded request body attachments opt-in.
+  - Return `416 Range Not Satisfiable` for unsatisfiable static file byte ranges.
+
 ### v3.0.0
 
 The 3.0.x series is considered a development release while the protocol HTTP application and controller interfaces stabilize.

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## v3.0.5
+
+  - **Breaking** Remove support for JavaScript packages installed in `lib/components`; use `node_modules` instead.
+  - **Breaking** Expose {ruby Utopia::Content::Middleware\#links} as the content link resolver rather than an indexed lookup method.
+  - **Security** Authenticate encrypted session cookies using AES-256-GCM. Existing session cookies are invalidated.
+  - Constrain content node local paths to the configured content root.
+  - **Security** Redact sensitive exception report fields and make bounded request body attachments opt-in.
+  - Return `416 Range Not Satisfiable` for unsatisfiable static file byte ranges.
+
 ## v3.0.0
 
 The 3.0.x series is considered a development release while the protocol HTTP application and controller interfaces stabilize.