empeira 0.1.0.pre.alpha.1

data/lib/empeira/network/proxy_policy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    class ProxyPolicy
+      LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?'
+      DOMAIN = /\A(?:\*\.)?#{LABEL}(?:\.#{LABEL})+\z/
+      # Destination IP restrictions apply only to the authenticated bootstrap proxy.
+      IPV4_FORBIDDEN = %w[0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16
+                          172.16.0.0/12 192.168.0.0/16 224.0.0.0/4 240.0.0.0/4].freeze
+      # Squid normalizes mapped addresses to IPv4 before interpreting the prefix.
+      # IPv6-sized prefixes are misparsed as ::/0, so retain the equivalent IPv4 prefix.
+      MAPPED_FORBIDDEN = IPV4_FORBIDDEN.map { |range| "::ffff:#{range}" }.freeze
+      FORBIDDEN = [*IPV4_FORBIDDEN, *MAPPED_FORBIDDEN, '::/128', '::1/128', 'fc00::/7', 'fe80::/10'].join(' ').freeze
+
+      def self.valid_domain?(value)
+        value.is_a?(String) && value.size <= 253 && value.match?(DOMAIN) &&
+          !value.delete_prefix('*.').match?(/\A[\d.]+\z/) &&
+          !value.end_with?('.empeira.internal', '.localhost') && value != 'empeira.internal'
+      end
+
+      def initialize(config, authorization: nil)
+        @config = config
+        @authorization = authorization
+      end
+
+      def configuration
+        [
+          'dns_nameservers @EMPEIRA_DNS@', 'http_port 3128',
+          'visible_hostname empeira-proxy', 'cache deny all',
+          'access_log none', 'cache_log /dev/null', 'pid_filename none',
+          client_rule, 'http_access deny !clients',
+          'request_header_access Proxy-Authorization deny all',
+          'acl SSL_ports port 443', 'acl Safe_ports port 80 443', 'acl CONNECT method CONNECT',
+          ("acl forbidden dst #{FORBIDDEN}" if @authorization), 'http_access deny !Safe_ports',
+          'http_access deny CONNECT !SSL_ports', ('http_access deny forbidden' if @authorization),
+          *destination_rules, 'http_access deny all', ''
+        ].compact.join("\n")
+      end
+
+      def self.domain_rules(domains, name: 'permitted', condition: nil)
+        return [] if domains.empty?
+
+        destinations = domains.map { |domain| domain.start_with?('*.') ? ".#{domain.delete_prefix('*.')}" : domain }
+        ["acl #{name} dstdomain -n #{destinations.join(' ')}",
+         "http_access allow #{[condition, name].compact.join(' ')}"]
+      end
+
+      private
+
+      def destination_rules
+        return self.class.domain_rules(@config.fetch('global')) if @authorization
+
+        ['include /empeira-proxy/proxy-rules.conf']
+      end
+
+      def client_rule
+        return 'acl clients src "/empeira-proxy/proxy-clients"' unless @authorization
+
+        "acl clients req_header Proxy-Authorization ^Basic[[:space:]]#{Regexp.escape(@authorization)}$"
+      end
+    end
+  end
+end

data/lib/empeira/network/redirects.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    # Observed owned service addresses are transient gateway inputs, never inventory mappings.
+    class Redirects
+      EXCLUDED_TARGETS = %w[gateway browser-ui].freeze
+
+      def self.target_key(entry)
+        key = entry.fetch('to').fetch('service')
+        key == 'coredns' ? 'dns' : key
+      end
+
+      def self.validate_routes!(entries, routes:)
+        entries.each_with_index do |entry, index|
+          source = entry.fetch('from').fetch('ip')
+          next unless DirectEgress::BENCHMARK.include?(source)
+
+          collision = routes.find { |range| IPAddr.new(range).include?(source) }
+          next unless collision
+
+          raise ConfigurationError,
+                "network.redirects[#{index}].from.ip collides with host/VPN/runtime route #{collision}"
+        end
+      rescue IPAddr::InvalidAddressError
+        raise Error, 'Cannot verify virtual redirect source route collisions', cause: nil
+      end
+
+      def self.validate!(entries, definitions:, subnet: nil)
+        entries.each_with_index do |entry, index|
+          path = "network.redirects[#{index}]"
+          target = target_key(entry)
+          unless definitions.key?(target) && !EXCLUDED_TARGETS.include?(target)
+            raise ConfigurationError, "#{path}.to.service #{target} is missing, disabled or not an internal " \
+                                      'application service'
+          end
+          next unless subnet && IPAddr.new(subnet).include?(entry.fetch('from').fetch('ip'))
+
+          raise ConfigurationError, "#{path}.from.ip collides with the workspace subnet #{subnet}"
+        end
+      end
+
+      def initialize(entries:, network:, subnet:)
+        @entries = entries
+        @network = network
+        @subnet = IPAddr.new(subnet)
+      end
+
+      def resolve(definitions:, resources:)
+        entries = @entries.map { |entry| resolved_entry(entry, definitions, resources) }
+        entries.sort_by do |entry|
+          entry.fetch('from').values_at('ip', 'port') + [entry.fetch('from').fetch('protocol', 'tcp')]
+        end
+      end
+
+      private
+
+      def resolved_entry(entry, definitions, resources)
+        key = self.class.target_key(entry)
+        ip = target_address(resources[key], definitions.fetch(key))
+        source = entry.fetch('from').dup
+        source.delete('protocol') if source['protocol'] == 'tcp'
+        { 'from' => source, 'to' => ip && { 'ip' => ip, 'port' => entry.fetch('to').fetch('port') } }
+      end
+
+      def target_address(resource, definition)
+        return unless resource
+
+        definition.verify!(resource)
+        return unless resource['state'] == 'running' &&
+                      resource.dig('labels', 'io.empeira.definition') == definition.fingerprint
+
+        ip = resource.dig('networks', @network, 'IPAddress')
+        unless valid_address?(ip)
+          raise Providers::OwnershipError, "Redirect target #{definition.key} has no valid workspace IPv4 address"
+        end
+
+        ip
+      rescue IPAddr::InvalidAddressError
+        raise Providers::OwnershipError, "Redirect target #{definition.key} has an invalid workspace address",
+              cause: nil
+      end
+
+      def valid_address?(ip)
+        ip.is_a?(String) && @subnet.include?(IPAddr.new(ip)) && IPAddr.new(ip).to_s == ip
+      end
+    end
+  end
+end

data/lib/empeira/network/resource.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Network
+    module ResourceIdentity
+      private
+
+      def valid_identity?(value)
+        value.is_a?(String) && value.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]*\z/)
+      end
+
+      def valid_labels?(labels)
+        labels.is_a?(Hash) && labels.all? { |key, value| key.is_a?(String) && value.is_a?(String) }
+      end
+    end
+
+    # Identity and isolation only; this cannot stand in for a deletion membership observation.
+    Binding = Data.define(:id, :name, :labels, :isolated) do
+      include ResourceIdentity
+
+      def initialize(id:, name:, labels:, isolated:)
+        unless valid_identity?(id) && valid_identity?(name) && valid_labels?(labels) && [true, false].include?(isolated)
+          raise Providers::ExecutionError, 'Runtime returned malformed network binding'
+        end
+
+        super(id: id.dup.freeze, name: name.dup.freeze, labels: Immutable.deep_freeze(labels.dup), isolated: isolated)
+      end
+    end
+
+    Resource = Data.define(:id, :name, :labels, :isolated, :attachment_count) do
+      include ResourceIdentity
+
+      def initialize(id:, name:, labels:, isolated:, attachment_count:)
+        unless valid_identity?(id) && valid_identity?(name) && valid_labels?(labels) &&
+               valid_policy?(isolated, attachment_count)
+          raise Providers::ExecutionError, 'Runtime returned malformed network data'
+        end
+
+        super(id: id.dup.freeze, name: name.dup.freeze, labels: Immutable.deep_freeze(labels.dup),
+              isolated: isolated, attachment_count: attachment_count)
+      end
+
+      private
+
+      def valid_policy?(isolated, count)
+        [true, false].include?(isolated) && count.is_a?(Integer) && count >= 0
+      end
+    end
+  end
+end

data/lib/empeira/node/agent_installer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    module AgentInstaller
+      module_function
+
+      def build(context:, runtime:, requirements:, execute:, copy:, progress: Progress.new)
+        AgentInstallation.new(context: context, runtime: runtime, requirements: requirements,
+                              execute: execute, copy: copy, progress: progress)
+      end
+    end
+
+    class AgentInstallation
+      def initialize(context:, runtime:, requirements:, execute:, copy:, progress:)
+        @acquisition = Agent::Acquisition.new(context: context, runtime: runtime, progress: progress)
+        @requirements = requirements
+        @execute = execute
+        @copy = copy
+      end
+
+      def install(proxy_url:)
+        @acquisition.with_package(@requirements) do |artifact|
+          AgentPackage.new(target: @requirements.target, package: @requirements.agent.fetch('package'),
+                           artifact: artifact, execute: @execute, copy: @copy,
+                           rpm_options: @requirements.rpm_options).install(proxy_url: proxy_url)
+        end
+      end
+    end
+  end
+end

data/lib/empeira/node/agent_package.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/FormatStringToken -- RPM and DNF use their native query-format tokens.
+
+module Empeira
+  module Node
+    # Installs one host-acquired artifact through the guest's native manager and original base sources.
+    class AgentPackage
+      PACKAGE_PATH = '/var/tmp/empeira-agent-package'
+
+      def initialize(target:, package:, artifact:, execute:, copy:, rpm_options: [])
+        @target = target
+        @package = package
+        @artifact = artifact
+        @execute = execute
+        @copy = copy
+        @rpm_options = rpm_options
+        @paths = []
+      end
+
+      def install(proxy_url:)
+        @proxy_url = proxy_url
+        @package_proxy = PackageProxy.new(family: @target.family, execute: @execute, copy: @copy)
+        @paths << @package_proxy.path
+        @package_proxy.prepare(proxy_url)
+        @paths << package_path
+        @copy.call(@artifact.path, package_path, '0600')
+        install_keys if @target.format == 'rpm'
+        install_package
+        verify_version!
+      ensure
+        cleanup
+      end
+
+      private
+
+      def cleanup
+        remove_introduced_keys if @original_keys
+      ensure
+        execute!(['rm', '-f', '--', *@paths], 'local agent artifact cleanup') unless @paths.empty?
+      end
+
+      def package_path
+        "#{PACKAGE_PATH}.#{@target.format}"
+      end
+
+      def install_package
+        if @target.format == 'deb'
+          options = ['-o', 'Acquire::http::AllowRedirect=false', '-o', 'Acquire::https::AllowRedirect=false',
+                     '-o', 'APT::Update::Error-Mode=any']
+          execute!(['apt-get', *@package_proxy.arguments, *options, 'update'], 'base dependency metadata acquisition')
+          execute!(['apt-get', *@package_proxy.arguments, *options, 'install', '-y', '--', package_path],
+                   'local APT agent installation (dependencies must be available in the original base sources)')
+        else
+          verification = @artifact.metadata.fetch('verify_signatures') ? 1 : 0
+          execute!(['dnf', *@package_proxy.arguments, "--setopt=localpkg_gpgcheck=#{verification}", *@rpm_options,
+                    'install', '--assumeyes', '--', package_path],
+                   'local DNF agent installation (dependencies must be available in the original base sources)')
+        end
+      end
+
+      def install_keys
+        @original_keys = signing_keys
+        @artifact.metadata.fetch('public_keys').each_with_index do |encoded, index|
+          path = "/var/tmp/empeira-agent-signing-key-#{index}"
+          @paths << path
+          PackageProxy.copy_text(@copy, Base64.strict_decode64(encoded), path)
+          execute!(['rpmkeys', '--import', path], 'temporary agent signing key import')
+        end
+      end
+
+      def signing_keys
+        result = execute!(['rpm', '-qa', '--qf', "%{NAME}-%{VERSION}-%{RELEASE}\n", 'gpg-pubkey'],
+                          'agent signing key ownership verification')
+        result.stdout.lines.map(&:strip).sort.tap do |keys|
+          raise Error, 'Cannot validate RPM signing key identity; Puppet was not run' unless
+            keys.all? { |key| key.match?(/\Agpg-pubkey-[a-f0-9]+-[a-f0-9]+\z/) }
+        end
+      end
+
+      def remove_introduced_keys
+        (signing_keys - @original_keys).each do |key|
+          execute!(['rpm', '-e', '--', key], 'temporary signing key cleanup')
+        end
+        raise Error, 'Cannot verify agent signing key cleanup; Puppet was not run' unless signing_keys == @original_keys
+      end
+
+      def installed_identity
+        command = identity_command
+        result = execute!(command, 'installed agent identity verification')
+        name, version, architecture = result.stdout.strip.split('|')
+        version = version.delete_prefix('0:') if @target.format == 'rpm' && version
+        [name, version, architecture]
+      end
+
+      def identity_command
+        if @target.format == 'deb'
+          ['dpkg-query', '-W', '-f=${Package}|${Version}|${Architecture}', @package]
+        else
+          ['rpm', '-q', '--qf', '%{NAME}|%{EPOCHNUM}:%{VERSION}-%{RELEASE}|%{ARCH}', @package]
+        end
+      end
+
+      def verify_version!
+        name, version, architecture = installed_identity
+        return if name == @package && version == @artifact.metadata.fetch('version') &&
+                  architecture == @artifact.metadata.fetch('architecture')
+
+        raise Error, 'Installed agent package identity differs from the resolved artifact; Puppet was not run'
+      end
+
+      def execute!(arguments, operation)
+        result = @execute.call(arguments)
+        return result if result.success?
+
+        text = PackageProxy.redact("#{result.stderr}\n#{result.stdout}", @proxy_url)
+        diagnostic = Execution::Diagnostics.native(result.with(stderr: text, stdout: ''),
+                                                   operation: "Agent #{operation}", tool: arguments.first)
+        raise Error, "Agent #{operation} failed; node retained and Puppet was not run\n#{diagnostic}", cause: nil
+      end
+    end
+  end
+end
+
+# rubocop:enable Style/FormatStringToken

data/lib/empeira/node/agent_repository.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'digest'
+require 'base64'
+
+module Empeira
+  module Node
+    # Native source setup and package inspection run only in an owned disposable helper.
+    # rubocop:disable-next Metrics/ClassLength -- APT metadata resolution and package inspection share one isolated source.
+    class AgentRepository
+      include Agent::NativeCommands
+
+      AUTH_PATH = '/etc/apt/auth.conf.d/00-empeira-agent.conf'
+      SOURCE_PATH = '/var/tmp/empeira-agent-sources/agent.list'
+      KEY_PATH = '/var/tmp/empeira-agent-key.gpg'
+      PACKAGE_PATH = '/var/tmp/empeira-agent-package.deb'
+      attr_reader :public_keys
+
+      # rubocop:disable-next Metrics/ParameterLists -- The helper receives explicit transport and target dependencies.
+      def initialize(source:, package:, version:, target:, execute:, copy:, download:, authentication:, directory:)
+        @source = source
+        @package = package
+        @version = version
+        @target = target
+        @execute = execute
+        @copy = copy
+        @download = download
+        @authentication = authentication
+        @directory = directory
+        @public_keys = []
+      end
+
+      def resolve
+        @release_package = nil
+        install_source
+        native!(['apt-get', *apt_options, 'update'], 'APT metadata acquisition')
+        result = native!(['apt-cache', *apt_options, 'show', '--', @package], 'APT package resolution')
+        candidates = result.stdout.split(/\n\s*\n/).filter_map { |stanza| apt_candidate(stanza) }
+        Agent::Versions.select(candidates, @version, suffix: @source['suffix'])
+      ensure
+        remove_release_package if @release_package
+      end
+
+      def inspect_package(path)
+        @copy.call(path, PACKAGE_PATH, '0600')
+        result = execute!(['dpkg-deb', '--show', '--showformat=${Package}|${Version}|${Architecture}', PACKAGE_PATH],
+                          'DEB package inspection')
+        name, version, architecture = result.stdout.strip.split('|')
+        validate_metadata(name, version, architecture)
+      end
+
+      def prepare_keys
+        return unless @source['key']
+
+        path = download_artifact(@source.fetch('key'), 'signing-key')
+        @public_keys << Base64.strict_encode64(File.binread(path))
+        key = File.binread(path).start_with?('-----BEGIN PGP PUBLIC KEY BLOCK-----') ? "#{KEY_PATH}.asc" : KEY_PATH
+        @copy.call(path, key, '0644')
+        key
+      end
+
+      private
+
+      def install_source
+        execute!(['mkdir', '-p', File.dirname(SOURCE_PATH), '/var/tmp/empeira-agent-lists/partial'],
+                 'source preparation')
+        if @source['release'] || !@source.key?('suite')
+          install_release(@source['release'] || @source)
+          collect_release_sources
+        else
+          install_repository
+        end
+      end
+
+      def install_repository
+        key = prepare_keys
+        options = []
+        options << "signed-by=#{key}" if key
+        options << 'trusted=yes' if @source['verify_signatures'] == false
+        line = "deb [#{options.join(' ')}] #{@source.fetch('url')} #{@source.fetch('suite')} " \
+               "#{@source.fetch('component')}\n"
+        copy_text(line.sub('[] ', ''), SOURCE_PATH, mode: '0644')
+      end
+
+      def install_release(artifact)
+        path = download_artifact(artifact, 'release.deb')
+        destination = '/var/tmp/empeira-agent-release.deb'
+        @copy.call(path, destination, '0600')
+        name = execute!(['dpkg-deb', '--field', destination, 'Package'], 'release metadata').stdout.strip
+        require_absent_release!(name)
+        @release_package = name
+        execute!(['dpkg', '-i', destination], 'release package installation')
+      end
+
+      def collect_release_sources
+        files = execute!(['dpkg-query', '-L', @release_package], 'release source discovery').stdout.lines.map(&:strip)
+        files = files.select do |file|
+          file.start_with?('/etc/apt/sources.list.d/') && file.match?(/\.(?:list|sources)\z/)
+        end
+        raise Error, 'Agent release package provides no native APT source' if files.empty?
+
+        files.each_with_index do |file, index|
+          copy_release_source(file, index)
+        end
+      end
+
+      def copy_release_source(file, index)
+        content = execute!(['cat', file], 'release source configuration').stdout
+        content = Agent::ReleaseSources.apt(content, format: File.extname(file), source: @source)
+        copy_text(content, "/var/tmp/empeira-agent-sources/#{index}#{File.extname(file)}", mode: '0644')
+      end
+
+      def apt_options
+        ['-o', 'Dir::Etc::sourcelist=/dev/null', '-o', 'Dir::Etc::sourceparts=/var/tmp/empeira-agent-sources',
+         '-o', 'Dir::State::lists=/var/tmp/empeira-agent-lists', '-o', 'Dir::State::status=/dev/null',
+         '-o', 'Acquire::http::AllowRedirect=false', '-o', 'Acquire::https::AllowRedirect=false',
+         '-o', 'APT::Update::Error-Mode=any']
+      end
+
+      def apt_candidate(stanza)
+        fields = apt_fields(stanza)
+        return unless apt_identity?(fields) && %w[Filename Version SHA256].all? { |key| fields[key] }
+
+        return unless Agent::Versions.match?(fields.fetch('Version'), @version, suffix: @source['suffix'])
+
+        { 'version' => fields.fetch('Version'), 'architecture' => fields.fetch('Architecture'),
+          'url' => package_url(fields.fetch('Version')), 'sha256' => fields.fetch('SHA256') }
+      end
+
+      def apt_fields(stanza)
+        stanza.lines.filter_map do |line|
+          line.split(': ', 2) if line.match?(/\A\w[^:]*: /)
+        end.to_h.transform_values(&:strip)
+      end
+
+      def apt_identity?(fields)
+        fields['Package'] == @package && [@target.native_architecture, 'all'].include?(fields['Architecture'])
+      end
+
+      def package_url(version)
+        result = native!(['apt-get', *apt_options, '--print-uris', 'download', "#{@package}=#{version}"],
+                         'APT artifact location')
+        urls = result.stdout.lines.filter_map { |line| line[%r{\A'(https://[^']+)'}, 1] }.uniq
+        raise Error, 'Selected agent source did not provide one HTTPS package location' unless urls.size == 1
+
+        urls.first
+      end
+
+      def validate_metadata(name, version, architecture)
+        unless name == @package && [@target.native_architecture, 'all'].include?(architecture) &&
+               Agent::Versions.match?(version.to_s, @version, suffix: @source['suffix'])
+          raise Error, 'Agent package name, native version or architecture differs from the requested target'
+        end
+
+        { 'version' => version, 'architecture' => architecture }
+      end
+    end
+  end
+end

data/lib/empeira/node/apt_configuration.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # Preserve the base image's complete APT configuration around temporary
+    # agent-repository and package-bootstrap changes.
+    class AptConfiguration
+      DISTRIBUTIONS = %w[ubuntu debian].freeze
+      BACKUP = '/root/.empeira-apt-before-bootstrap.tar'
+
+      def initialize(os:, execute:, root: '/', backup: BACKUP, on_retry: nil)
+        @os = os
+        @execute = execute
+        @root = Pathname(root).cleanpath
+        @backup = Pathname(backup).cleanpath
+        @on_retry = on_retry
+      end
+
+      def preserve
+        return yield unless DISTRIBUTIONS.include?(@os)
+
+        capture!
+        begin
+          yield
+        ensure
+          restore!
+        end
+      end
+
+      private
+
+      def capture!
+        execute!(['install', '--mode', '0600', '/dev/null', @backup.to_s], 'Cannot prepare APT configuration backup')
+        execute!(['tar', '--create', '--file', @backup.to_s, '--directory', @root.to_s, 'etc/apt'],
+                 'Cannot preserve the base image APT configuration')
+      rescue StandardError => e
+        cleanup = @execute.call(['rm', '--force', '--', @backup.to_s])
+        unless cleanup.success?
+          details = Execution::Diagnostics.command(cleanup, operation: 'Partial APT backup cleanup', tool: 'rm')
+          raise Error, "#{e.message}\nPartial APT backup cleanup also failed\n#{details}", cause: nil
+        end
+        raise
+      end
+
+      def restore!
+        execute!(['tar', '--list', '--file', @backup.to_s], restore_error)
+        execute!(['rm', '--recursive', '--force', '--', @root.join('etc/apt').to_s], restore_error)
+        execute!(['tar', '--extract', '--file', @backup.to_s, '--directory', @root.to_s], restore_error)
+        execute!(['tar', '--compare', '--file', @backup.to_s, '--directory', @root.to_s], restore_error)
+        remove_backup!
+      end
+
+      def remove_backup!
+        retried = false
+        begin
+          execute!(['rm', '--force', '--', @backup.to_s],
+                   'Cannot remove the restored APT configuration backup; ' \
+                   'Puppet was not run. Node retained for diagnosis')
+        rescue ::Empeira::VM::Guest::TransportError => e
+          raise unless e.transient? && !retried
+
+          retried = true
+          @on_retry&.call("Retrying only the restored APT backup removal once after a transient SSH error.\n" \
+                          "#{e.message}")
+          retry
+        end
+      end
+
+      def restore_error
+        'Cannot restore and verify the base image APT configuration; Puppet was not run. Node retained for diagnosis'
+      end
+
+      def execute!(arguments, message)
+        result = @execute.call(arguments)
+        return if result.success?
+
+        details = Execution::Diagnostics.command(result, operation: "#{message} (#{arguments.first} #{arguments[1]})",
+                                                         tool: arguments.first)
+        raise Error, "#{message}\n#{details}", cause: nil
+      rescue ::Empeira::VM::Guest::TransportError => e
+        raise e.with_context(message), cause: nil
+      end
+    end
+  end
+end

data/lib/empeira/node/bootstrap.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Empeira
+  module Node
+    # The complete Empeira-owned guest file state required before the first catalog.
+    class Bootstrap
+      FileEntry = Struct.new(:path, :content, :mode, keyword_init: true)
+
+      attr_reader :files
+
+      def initialize(provider:)
+        @files = [FileEntry.new(path: ExternalFact::PATH, content: ExternalFact.content(provider),
+                                mode: 0o644).freeze].freeze
+      end
+    end
+  end
+end