empeira 0.1.0.pre.alpha.1

data/lib/empeira/configuration/merge.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    module Merge
+      module_function
+
+      def call(lower, higher, path: [])
+        lower = agent_override_base(lower, higher, path)
+        lower = ImageSchema.override_base(lower, higher) if path.first == 'images' && path.size == 2
+        copy(lower).merge(copy(higher)) do |key, old, replacement|
+          old.is_a?(Hash) && replacement.is_a?(Hash) ? call(old, replacement, path: path + [key]) : replacement
+        end
+      end
+
+      def agent_override_base(lower, higher, path)
+        return lower unless path.first == 'agent'
+
+        base = copy(lower)
+        if path == %w[agent install]
+          override_agent_defaults!(base, higher)
+        elsif higher.key?('url') && higher['url'] != base['url'] && !higher.key?('sha256')
+          base.delete('sha256')
+        end
+        base
+      end
+
+      def override_agent_defaults!(base, higher)
+        %w[apt dnf].each do |manager|
+          next unless higher.dig(manager, 'default', 'url')
+
+          prefix = manager == 'apt' ? /\A(?:ubuntu|debian)/ : /\Ael/
+          base.fetch('repositories', {}).delete_if { |key, _| key.match?(prefix) }
+          base.fetch(manager, {}).clear
+        end
+      end
+
+      def copy(value)
+        case value
+        when Hash then value.to_h { |key, child| [copy(key), copy(child)] }
+        when Array then value.map { |child| copy(child) }
+        when String then value.dup
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/empeira/configuration/network_redirects.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    class NetworkRedirects
+      UNROUTABLE = %w[0.0.0.0/8 127.0.0.0/8 169.254.0.0/16 224.0.0.0/3].map { |value| IPAddr.new(value) }.freeze
+
+      def self.validate!(entries, path)
+        raise ConfigurationError, "#{path} must be an array" unless entries.is_a?(Array)
+
+        sources = entries.each_with_index.map do |entry, index|
+          validate_entry!(entry, "#{path}[#{index}]")
+        end
+        return if sources.uniq == sources
+
+        raise ConfigurationError,
+              "#{path} contains duplicate source IP/port/protocol tuples"
+      end
+
+      def self.validate_entry!(entry, path)
+        mapping!(entry, %w[from to], path)
+        source!(entry.fetch('from'), "#{path}.from")
+        target!(entry.fetch('to'), "#{path}.to")
+        source = entry.fetch('from')
+        udp_target!(entry, path) if source.fetch('protocol', 'tcp') == 'udp'
+        source.values_at('ip', 'port') + [source.fetch('protocol', 'tcp')]
+      end
+
+      def self.mapping!(value, keys, path)
+        return if value.is_a?(Hash) && value.keys.sort == keys.sort
+
+        raise ConfigurationError, "#{path} requires only #{keys.join(' and ')}"
+      end
+
+      def self.source!(value, path)
+        mapping!(value.is_a?(Hash) ? value.except('protocol') : value, %w[ip port], path)
+        unless %w[tcp udp].include?(value.fetch('protocol', 'tcp'))
+          raise ConfigurationError, "#{path}.protocol must be tcp or udp (default: tcp)"
+        end
+
+        Network::DirectEgress.validate_ip!(value.fetch('ip'), path, allow_benchmark: true)
+        if UNROUTABLE.any? { |range| range.include?(value.fetch('ip')) }
+          raise ConfigurationError, "#{path}.ip must be a routable unicast IPv4 address"
+        end
+
+        port!(value.fetch('port'), "#{path}.port")
+      end
+
+      def self.udp_target!(entry, path)
+        return if entry.dig('from', 'port') == 53 && entry.dig('to', 'port') == 53 &&
+                  %w[dns coredns].include?(entry.dig('to', 'service'))
+
+        raise ConfigurationError, "#{path}: UDP redirects require port 53 and the built-in coredns service"
+      end
+
+      def self.target!(value, path)
+        mapping!(value, %w[service port], path)
+        service = value.fetch('service')
+        unless service.is_a?(String) && service.match?(/\A#{Network::DirectEgress::DNS_LABEL}\z/)
+          raise ConfigurationError, "#{path}.service must be an internal service name"
+        end
+
+        port!(value.fetch('port'), "#{path}.port")
+      end
+
+      def self.port!(value, path)
+        return if value.is_a?(Integer) && value.between?(1, 65_535)
+
+        raise ConfigurationError, "#{path} must be an integer port from 1 through 65535"
+      end
+    end
+  end
+end

data/lib/empeira/configuration/node_images.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    # Node image metadata and architecture validation.
+    module NodeImages
+      module_function
+
+      def mapping!(value, path)
+        raise ConfigurationError, "#{path} must be a mapping" unless value.is_a?(Hash)
+      end
+
+      def catalog!(value, path)
+        mapping!(value, path)
+        value.each do |key, item|
+          unless key.is_a?(String) && key.match?(/\A[a-z0-9][a-z0-9_.-]*\z/)
+            raise ConfigurationError, "#{path} has an invalid catalog key"
+          end
+
+          yield item, "#{path}.#{key}"
+        end
+      end
+
+      def validate!(value, path, &)
+        catalog!(value, path, &)
+      end
+
+      def nodes(data, path)
+        catalog!(data, path) do |versions, os_path|
+          catalog!(versions, os_path) do |image, image_path|
+            node_image!(image, image_path)
+          end
+        end
+      end
+
+      def node_image!(image, path)
+        mapping!(image, path)
+        ImageSchema.validate!(image.except('architectures', 'build'), path)
+        ImageSchema.validate!({ 'build' => image['build'] }, path) if image.key?('build')
+        return unless image.key?('architectures')
+
+        architectures = image['architectures']
+        return if architectures.is_a?(Array) && !architectures.empty? &&
+                  (architectures - %w[amd64 arm64]).empty?
+
+        raise ConfigurationError, "#{path}.architectures must contain amd64 and/or arm64"
+      end
+
+      def effective!(images)
+        images.fetch('nodes').each do |os, versions|
+          versions.each do |version, image|
+            path = "images.nodes.#{os}.#{version}"
+            required!(image, ['architectures'], path)
+            ImageSchema.validate!(image.except('architectures', 'build'), path, effective: true)
+          end
+        end
+      end
+
+      def required!(data, keys, path)
+        keys.each { |key| raise ConfigurationError, "#{path}.#{key} is required" unless data.key?(key) }
+      end
+    end
+  end
+end

data/lib/empeira/configuration/schema.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Empeira
+  module Configuration
+    # Keep the public schema and its fragment/effective validation in one boundary.
+    # rubocop:disable-next Metrics/ClassLength
+    class Schema
+      CONTAINER_ENGINES = Runtime.registry.names
+      DNS_LABEL = '[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?'
+      DNS_NAME = /\A#{DNS_LABEL}(?:\.#{DNS_LABEL})*\.?\z/
+      RULES = {
+        'version' => :version,
+        'requirements' => { 'empeira' => :requirement },
+        'runtime' => { 'container_engine' => :engine },
+        'modules' => { 'path' => :module_path },
+        'addons' => :addons,
+        'server' => { 'runtime' => :server_runtime, 'mounts' => :server_mounts,
+                      'environment' => :environment,
+                      'memory' => :positive_integer, 'cpus' => :positive_integer, 'timeout' => :positive_integer },
+        'puppetdb' => { 'enabled' => :boolean, 'memory' => :positive_integer, 'runtime' => :puppetdb_runtime },
+        'network' => { 'egress' => :network_egress, 'redirects' => :network_redirects },
+        'proxy' => { 'enabled' => :boolean, 'global' => :allowlist, 'rules' => :proxy_rules },
+        'vm' => { 'disk' => :vm_disk, 'interfaces' => :vm_interfaces,
+                  'console' => { 'root_password' => :optional_string } },
+        'dns' => { 'upstream' => { 'mode' => :dns_mode, 'servers' => :dns_servers },
+                   'additional_resolver' => :additional_resolver, 'rewrites' => :dns_rewrites },
+        'node_defaults' => { 'init' => :node_init, 'os' => :optional_string, 'version' => :optional_string,
+                             'memory' => :positive_integer, 'cpus' => :positive_integer },
+        'mocks' => { 'commands' => :command_mocks },
+        'hiera' => { 'mounts' => :hiera_mounts },
+        'eyaml' => { 'enabled' => :boolean, 'private_key' => :optional_string, 'public_key' => :optional_string },
+        'images' => { 'registry' => :registry, 'network_adapter_builder' => :image,
+                      'server' => :image, 'puppetdb' => :image, 'postgres' => :image,
+                      'dns' => :image, 'proxy' => :image, 'direct_egress' => :image,
+                      'relay' => :image, 'r10k' => :image,
+                      'nodes' => :node_images },
+        'agent' => :agent,
+        'bootstrap' => { 'enabled' => :boolean, 'scripts' => :bootstrap_scripts,
+                         'packages' => :bootstrap_packages, 'guests' => :bootstrap_guests },
+        'browser' => { 'start_url' => :browser_start_url,
+                       'image' => { 'repository' => :image_repository, 'tag' => :image_tag } },
+        'containers' => { 'additional' => :additional_services }
+      }.tap { |rules| Immutable.deep_freeze(rules) }
+
+      # Schema fields containing secrets or opaque user-supplied content. Never export
+      # these to addons, even when their nested keys do not resemble secret names.
+      ADDON_PRIVATE_PATHS = [
+        %w[vm console root_password], %w[eyaml private_key], %w[browser start_url],
+        %w[server runtime startup arguments], %w[puppetdb runtime java_arguments],
+        %w[puppetdb runtime main_arguments], %w[containers additional * environment],
+        %w[containers additional * command], %w[containers additional * configuration content],
+        %w[addons * config]
+      ].tap { |paths| Immutable.deep_freeze(paths) }
+
+      CHECKS = {
+        registry: [Images::Reference.method(:registry?),
+                   'must be null or a registry host with a dot, port or localhost (no scheme or path)'],
+        browser_start_url: [->(v) { v.is_a?(String) && !v.strip.empty? && !v.match?(/\p{Cc}/) },
+                            'must be a nonempty string without control characters'],
+        module_path: [->(v) { v.is_a?(String) && !v.strip.empty? && !v.match?(/[\x00-\x1f\x7f,]/) },
+                      'must be a nonempty directory path without commas or control characters'],
+        image_repository: [->(v) { v.is_a?(String) && v.match?(Images::Configuration::REPOSITORY) },
+                           'must be an image repository'],
+        image_tag: [->(v) { v.is_a?(String) && v.match?(Images::Configuration::TAG) }, 'must be an image tag'],
+        node_init: [->(v) { %w[process systemd].include?(v) }, 'must be process or systemd'],
+        dns_mode: [->(v) { %w[host explicit].include?(v) }, 'must be host or explicit'],
+        dns_servers: [lambda do |v|
+          v.is_a?(Array) && v.all? do |address|
+            address.is_a?(String) && IPAddr.new(address).ipv4? && IPAddr.new(address).to_s == address
+          end
+        rescue IPAddr::InvalidAddressError
+          false
+        end, 'must contain canonical IPv4 DNS resolver addresses; IPv6 is not supported'],
+        additional_resolver: [lambda do |v|
+          v.nil? || (v.is_a?(String) && v.size <= 253 &&
+            ((v.match?(DNS_NAME) && !v.match?(/\A[\d.]+\z/)) || (IPAddr.new(v).ipv4? && IPAddr.new(v).to_s == v)))
+        rescue IPAddr::InvalidAddressError
+          false
+        end, 'must be null, a DNS name, or a canonical IPv4 address; IPv6 is not supported'],
+        environment: [lambda { |v|
+          v.is_a?(String) && v.match?(/\A[a-z][a-z0-9_]*\z/)
+        }, 'must be a Puppet environment name'],
+        allowlist: [->(v) { v.is_a?(Array) && v.all? { |d| Network::ProxyPolicy.valid_domain?(d) } },
+                    'must contain lowercase DNS domains or *.domain entries (no URLs, IPs or whitespace)'],
+        bootstrap_scripts: [lambda { |v|
+          v.is_a?(Array) && v.all? do |path|
+            path.is_a?(String) && !path.empty? && !path.start_with?('/') &&
+              !path.include?("\0") && !path.split('/').intersect?(%w[. ..])
+          end
+        }, 'must list relative local script paths within the project'],
+        version: [->(v) { v.is_a?(Integer) && v == 1 }, 'must be the supported schema version 1'],
+        engine: [->(v) { CONTAINER_ENGINES.include?(v) }, "must be one of: #{CONTAINER_ENGINES.join(', ')}"],
+        boolean: [->(v) { [true, false].include?(v) }, 'must be a boolean'],
+        optional_string: [lambda { |v|
+          v.nil? || (v.is_a?(String) && !v.strip.empty? && v == v.strip)
+        }, 'must be a non-empty string or null (without surrounding whitespace)'],
+        positive_integer: [->(v) { v.is_a?(Integer) && v.positive? }, 'must be a positive integer'],
+        vm_disk: [->(v) { v.is_a?(Integer) && (1..2048).cover?(v) },
+                  'must be an integer from 1 to 2048 GiB']
+      }.tap { |checks| Immutable.deep_freeze(checks) }
+
+      def initialize(cross_field_rules: [])
+        @cross_field_rules = cross_field_rules.dup.freeze
+      end
+
+      def validate_effective!(data)
+        validate_fragment!(data)
+        require_keys!(data, RULES, [])
+        CommandMocks.validate!(data.dig('mocks', 'commands'), 'mocks.commands', effective: true)
+        Addons.validate!(data.fetch('addons'), effective: true)
+        validate_operational!(data)
+        @cross_field_rules.each { |rule| rule.call(data) }
+        data
+      end
+
+      def validate_fragment!(data)
+        validate_mapping!(data, RULES, [])
+        data
+      end
+
+      private
+
+      def validate_operational!(data)
+        validate_images!(data.fetch('images'))
+        NodeImages.effective!(data.fetch('images'))
+        Server::Runtime.resolve(data)
+        Server::PuppetDBRuntime.resolve(data)
+        validate_dns!(data.dig('dns', 'upstream'))
+        validate_bootstrap!(data.fetch('bootstrap'))
+        AgentSchema.effective!(data.fetch('agent'))
+      end
+
+      def validate_bootstrap!(bootstrap)
+        BootstrapGuests.effective!(bootstrap.fetch('guests'))
+        Node::PackageBootstrap.validate!(bootstrap.fetch('packages'), 'bootstrap.packages', effective: true)
+        return if bootstrap.fetch('enabled') || bootstrap.fetch('scripts').empty?
+
+        raise ConfigurationError, 'bootstrap.scripts requires bootstrap.enabled=true'
+      end
+
+      def validate_dns!(upstream)
+        return unless (upstream['mode'] == 'explicit') == upstream['servers'].empty?
+
+        raise ConfigurationError, 'dns.upstream.servers must be nonempty in explicit mode and empty in host mode'
+      end
+
+      def validate_images!(images)
+        %w[server puppetdb postgres dns proxy direct_egress relay r10k network_adapter_builder].each do |key|
+          ImageSchema.validate!(images[key], "images.#{key}", effective: true)
+        end
+      end
+
+      def require_keys!(data, rules, path)
+        rules.each do |key, rule|
+          child_path = path + [key]
+          raise ConfigurationError, "#{child_path.join('.')} is required" unless data.key?(key)
+
+          require_keys!(data.fetch(key), rule, child_path) if rule.is_a?(Hash)
+        end
+      end
+
+      def validate_mapping!(data, rules, path)
+        location = path.empty? ? '$' : path.join('.')
+        raise ConfigurationError, "#{location} must be a mapping" unless data.is_a?(Hash)
+
+        data.each do |key, value|
+          # Do not echo untrusted keys: they may contain credentials or YAML values.
+          raise ConfigurationError, "#{location} contains a non-string key" unless key.is_a?(String)
+
+          child_path = path + [key]
+          unless rules.key?(key)
+            if child_path == %w[network internet]
+              validate_value!(value, :boolean, child_path)
+              next
+            end
+
+            raise ConfigurationError,
+                  "#{child_path.join('.')} is not a supported configuration key"
+          end
+
+          validate_value!(value, rules.fetch(key), child_path)
+        end
+      end
+
+      # rubocop:disable-next Metrics/AbcSize -- One schema-to-validator dispatch table.
+      def structured_validator(rule)
+        { additional_services: AdditionalServices.method(:validate!), proxy_rules: Network::HostPolicy.method(:validate!),
+          hiera_mounts: HieraMountSchema.method(:validate!), command_mocks: CommandMocks.method(:validate!),
+          server_mounts: ServerMounts.method(:validate!), dns_rewrites: DNSRewrites.method(:validate!),
+          image: ImageSchema.method(:validate!), addons: Addons.method(:validate!),
+          node_images: NodeImages.method(:nodes),
+          agent: AgentSchema.method(:validate!), bootstrap_guests: BootstrapGuests.method(:validate!),
+          bootstrap_packages: Node::PackageBootstrap.method(:validate!),
+          network_egress: Network::DirectEgress.method(:validate!),
+          network_redirects: NetworkRedirects.method(:validate!),
+          vm_interfaces: VMInterfaces.method(:validate!),
+          server_runtime: Server::Runtime.method(:validate!),
+          puppetdb_runtime: Server::PuppetDBRuntime.method(:validate!) }[rule]
+      end
+
+      def validate_value!(value, rule, path)
+        return validate_mapping!(value, rule, path) if rule.is_a?(Hash)
+        return VersionRequirement.parse(value) if rule == :requirement
+
+        validator = structured_validator(rule)
+        return validator.call(value, path.join('.')) if validator
+
+        check, message = CHECKS.fetch(rule)
+        raise ConfigurationError, "#{path.join('.')} #{message}" unless check.call(value)
+      end
+    end
+  end
+end

data/lib/empeira/configuration/server_mounts.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module Empeira
+  module Configuration
+    # Resolve explicit host data without exposing runtime-specific mount options.
+    class ServerMounts
+      FIELDS = %w[source target readonly].freeze
+      RESERVED = %w[/dev /proc /sys].freeze
+
+      def self.validate!(entries, path = 'server.mounts')
+        raise ConfigurationError, "#{path} must be an array of mounts" unless entries.is_a?(Array)
+
+        targets = entries.each_with_index.map do |entry, index|
+          validate_entry!(entry, "#{path}[#{index}]")
+          Pathname(entry.fetch('target')).cleanpath.to_s
+        end
+        targets.each_with_index do |target, index|
+          next unless targets.take(index).any? { |other| overlap?(target, other) }
+
+          raise ConfigurationError, "#{path}[#{index}].target overlaps another server mount target"
+        end
+      end
+
+      def self.safe_path?(value)
+        value.is_a?(String) && !value.strip.empty? && !value.match?(/[\p{Cc},]/)
+      end
+
+      def self.overlap?(left, right)
+        left == '/' || right == '/' || HieraMountSchema.overlap?(left, right)
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- Validate the small public mapping together.
+      def self.validate_entry!(entry, path)
+        raise ConfigurationError, "#{path} must be a mount mapping" unless entry.is_a?(Hash)
+        unless (entry.keys - FIELDS).empty?
+          raise ConfigurationError,
+                "#{path} only supports source, target and readonly"
+        end
+        raise ConfigurationError, "#{path}.source must be a safe local path" unless safe_path?(entry['source'])
+
+        target = entry['target']
+        unless safe_path?(target) && Pathname(target).absolute? && !target.split('/').include?('..')
+          raise ConfigurationError, "#{path}.target must be an absolute path without .., commas or control characters"
+        end
+        if RESERVED.any? { |reserved| overlap?(Pathname(target).cleanpath.to_s, reserved) }
+          raise ConfigurationError, "#{path}.target must not cover /, /dev, /proc or /sys"
+        end
+        return unless entry.key?('readonly') && ![true, false].include?(entry['readonly'])
+
+        raise ConfigurationError, "#{path}.readonly must be a boolean"
+      end
+
+      attr_reader :entries
+
+      def initialize(entries:, project:)
+        self.class.validate!(entries)
+        @entries = entries.each_with_index.map do |entry, index|
+          { 'source' => resolve(entry.fetch('source'), project, index),
+            'target' => Pathname(entry.fetch('target')).cleanpath.to_s,
+            'readonly' => entry.fetch('readonly', true) }
+        end
+      end
+
+      def verify_targets!(managed_targets)
+        entries.each_with_index do |entry, index|
+          next unless managed_targets.any? { |target| self.class.overlap?(entry.fetch('target'), target) }
+
+          raise ConfigurationError, "server.mounts[#{index}].target overlaps an Empeira-managed server mount"
+        end
+      end
+
+      private
+
+      def resolve(value, project, index)
+        source = Pathname(value).expand_path(project).realpath
+        unless data_source?(source)
+          raise ConfigurationError, "server.mounts[#{index}].source must resolve to a regular file or data directory"
+        end
+
+        verify_data_tree!(source, index) if source.directory?
+        source.to_s
+      rescue SystemCallError
+        raise ConfigurationError, "server.mounts[#{index}].source must exist and allow canonical resolution",
+              cause: nil
+      end
+
+      def data_source?(source)
+        self.class.safe_path?(source.to_s) && (source.file? || source.directory?) &&
+          RESERVED.none? { |reserved| self.class.overlap?(source.to_s, reserved) }
+      end
+
+      def verify_data_tree!(source, index)
+        # Do not follow directory symlinks or read file contents. Reject socket/device directories too.
+        Find.find(source.to_s, ignore_error: false) do |path|
+          stat = File.lstat(path)
+          next if stat.file? || stat.directory? || stat.symlink?
+
+          raise ConfigurationError,
+                "server.mounts[#{index}].source must not expose sockets, devices or other special files"
+        end
+      end
+    end
+  end
+end

data/lib/empeira/configuration/service_configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    class ServiceConfiguration
+      RUNTIME_TARGETS = %w[/etc/hosts /etc/hostname /etc/resolv.conf].freeze
+
+      def self.validate!(value, path)
+        unless value.is_a?(Hash) && value.size == 2 && %w[content target].all? { |key| value.key?(key) }
+          raise ConfigurationError, "#{path} must contain only target and content"
+        end
+
+        target = value['target']
+        unless safe_target?(target)
+          raise ConfigurationError, "#{path}.target must be a safe absolute file path without traversal"
+        end
+
+        validate_targets!(target, RUNTIME_TARGETS, path)
+        serialize(value['content'], path)
+      end
+
+      def self.safe_target?(target)
+        target.is_a?(String) && target.start_with?('/') && HieraMountSchema.safe_target?(target.delete_prefix('/'))
+      end
+
+      def self.validate_targets!(target, targets, path, field: 'target')
+        return unless targets.any? { |other| other == '/' || HieraMountSchema.overlap?(target, other) }
+
+        raise ConfigurationError, "#{path}.#{field} overlaps an existing managed mount target"
+      end
+
+      def self.serialize(content, path)
+        YAML.safe_dump(content, permitted_classes: [], permitted_symbols: [], aliases: false, line_width: -1)
+      rescue Psych::Exception
+        raise ConfigurationError, "#{path}.content must contain only YAML data without objects, tags or aliases",
+              cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/configuration/ssh_preferences.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Empeira
+  module Configuration
+    # Personal login preferences are resolved independently of infrastructure definitions.
+    class SSHPreferences
+      FIELDS = %w[user identity port].freeze
+      KEYS = [*FIELDS, 'rules'].freeze
+      USER = /\A[a-zA-Z0-9_.@-]+\z/
+
+      def self.validate!(data, path = 'ssh')
+        mapping!(data, KEYS, path)
+        fields!(data, path)
+        rules = data.fetch('rules', [])
+        raise ConfigurationError, "#{path}.rules must be an array" unless rules.is_a?(Array)
+
+        rules.each_with_index { |rule, index| rule!(rule, "#{path}.rules.#{index}") }
+      end
+
+      def self.mapping!(data, keys, path)
+        raise ConfigurationError, "#{path} must be a mapping" unless data.is_a?(Hash)
+
+        data.each_key do |key|
+          raise ConfigurationError, "#{path} contains a non-string key" unless key.is_a?(String)
+          raise ConfigurationError, "#{path}.#{key} is not a supported configuration key" unless keys.include?(key)
+        end
+      end
+
+      def self.fields!(data, path)
+        if data.key?('user') && !(data['user'].is_a?(String) && data['user'].match?(USER))
+          raise ConfigurationError, "#{path}.user must be a valid login name"
+        end
+
+        identity!(data['identity'], path) if data.key?('identity')
+        port!(data['port'], "#{path}.port") if data.key?('port')
+      end
+
+      def self.port!(value, path = 'SSH port')
+        return value if value.is_a?(Integer) && value.between?(1, 65_535)
+
+        raise ConfigurationError, "#{path} must be an integer from 1 to 65535"
+      end
+
+      def self.identity!(value, path)
+        return if value.is_a?(String) && !value.match?(/[\p{Cc}\p{Cf}]/) &&
+                  (value.start_with?('~/') || Pathname(value).absolute?)
+
+        raise ConfigurationError, "#{path}.identity must be an absolute path or start with ~/"
+      end
+
+      def self.rule!(rule, path)
+        mapping!(rule, [*FIELDS, 'hosts'], path)
+        fields!(rule, path)
+        unless rule.keys.intersect?(FIELDS)
+          raise ConfigurationError, "#{path} requires at least one of user, identity or port"
+        end
+
+        hosts = rule['hosts']
+        return if hosts.is_a?(Array) && !hosts.empty? && hosts.all? { |pattern| HostnamePattern.valid?(pattern) }
+
+        raise ConfigurationError, "#{path}.hosts must contain full hostname globs using * and ?"
+      end
+
+      def initialize(config = {})
+        @config = config
+      end
+
+      # rubocop:disable-next Metrics/CyclomaticComplexity -- Three independent preference fields share one matcher.
+      def resolve(hostname:, user: nil, identity: nil, port: nil)
+        self.class.port!(port) unless port.nil?
+        fields = @config.slice(*FIELDS)
+        @config.fetch('rules', []).each do |rule|
+          fields.merge!(rule.slice(*FIELDS)) if rule.fetch('hosts').any? do |pattern|
+            HostnamePattern.matches?(pattern, hostname)
+          end
+        end
+        { user: user || fields['user'], identity: identity || fields['identity'], port: port || fields['port'] }
+      end
+    end
+  end
+end

data/lib/empeira/configuration/user.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Configuration
+    # Host preferences only; project behavior remains defined by the control repository.
+    class User
+      KEYS = { 'runtime' => ['container_engine'].freeze, 'images' => ['registry'].freeze,
+               'ssh' => SSHPreferences::KEYS }.freeze
+
+      def initialize(path:, schema: Schema.new)
+        @path = path
+        @schema = schema
+      end
+
+      def load
+        return {} unless @path.exist? || @path.symlink?
+
+        data = Document.new.read(@path)
+        validate_keys!(data)
+        SSHPreferences.validate!(data.fetch('ssh')) if data.key?('ssh')
+        @schema.validate_fragment!(data.except('ssh'))
+        data
+      rescue ConfigurationError => e
+        raise ConfigurationError, "#{@path}: #{e.message}", cause: nil
+      end
+
+      private
+
+      def validate_keys!(data)
+        raise ConfigurationError, '$ must be a mapping' unless data.is_a?(Hash)
+
+        data.each do |section, values|
+          reject!(section) unless KEYS.key?(section)
+          raise ConfigurationError, "#{section} must be a mapping" unless values.is_a?(Hash)
+
+          values.each_key { |key| reject!("#{section}.#{key}") unless KEYS.fetch(section).include?(key) }
+        end
+      end
+
+      def reject!(path)
+        raise ConfigurationError, "#{path} is not allowed; user configuration may only configure " \
+                                  'runtime.container_engine, images.registry and ssh preferences'
+      end
+    end
+  end
+end