empeira 0.1.0.pre.alpha.1

data/lib/empeira.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative 'empeira/errors'
+require_relative 'empeira/progress'
+require_relative 'empeira/build_info'
+require_relative 'empeira/immutable'
+require_relative 'empeira/hostname_pattern'
+require_relative 'empeira/project_root'
+require_relative 'empeira/providers/registry'
+require_relative 'empeira/providers/resource'
+require_relative 'empeira/providers/lifecycle'
+require_relative 'empeira/runtime/interface'
+require_relative 'empeira/vm/interface'
+require_relative 'empeira/platform/kvm'
+require_relative 'empeira/vm/prerequisites'
+require_relative 'empeira/vm/qemu'
+require_relative 'empeira/node/interface'
+require_relative 'empeira/node/diagnostic_command'
+require_relative 'empeira/images/source'
+require_relative 'empeira/runtime/container'
+require_relative 'empeira/runtime/service_inspection'
+require_relative 'empeira/runtime/service_arguments'
+require_relative 'empeira/runtime/service_images'
+require_relative 'empeira/runtime/image_metadata'
+require_relative 'empeira/runtime/registry_diagnostics'
+require_relative 'empeira/runtime/recipe_build'
+require_relative 'empeira/runtime/services'
+require_relative 'empeira/runtime/diagnostic_execution'
+require_relative 'empeira/runtime/workspace_network'
+require_relative 'empeira/runtime/update_helper'
+require_relative 'empeira/runtime/agent_helper'
+require_relative 'empeira/runtime/mount_probe'
+require_relative 'empeira/runtime/docker'
+require_relative 'empeira/runtime/podman'
+require_relative 'empeira/providers'
+require_relative 'empeira/network/policy'
+require_relative 'empeira/network/resource'
+require_relative 'empeira/network/definition'
+require_relative 'empeira/network/egress'
+require_relative 'empeira/network/peer/layout'
+require_relative 'empeira/network/direct_egress'
+require_relative 'empeira/network/gateway'
+require_relative 'empeira/network/redirects'
+require_relative 'empeira/images/configuration'
+require_relative 'empeira/images/reference'
+require_relative 'empeira/images/recipe'
+require_relative 'empeira/server/runtime'
+require_relative 'empeira/server/environment_configuration'
+require_relative 'empeira/server/puppetdb_runtime'
+require_relative 'empeira/server/http'
+require_relative 'empeira/server/relay_certificate'
+require_relative 'empeira/node/external_fact'
+require_relative 'empeira/node/bootstrap'
+require_relative 'empeira/node/package_proxy'
+require_relative 'empeira/node/package_bootstrap'
+require_relative 'empeira/network/naming'
+require_relative 'empeira/network/proxy_policy'
+require_relative 'empeira/network/host_policy'
+require_relative 'empeira/network/proxy_bindings'
+require_relative 'empeira/network/bootstrap_proxy'
+require_relative 'empeira/services/definition'
+require_relative 'empeira/configuration/document'
+require_relative 'empeira/configuration/merge'
+require_relative 'empeira/configuration/image_schema'
+require_relative 'empeira/configuration/node_images'
+require_relative 'empeira/configuration/agent_values'
+require_relative 'empeira/configuration/agent_schema'
+require_relative 'empeira/configuration/hiera_mount_schema'
+require_relative 'empeira/configuration/hiera_modulepath'
+require_relative 'empeira/configuration/hiera_mounts'
+require_relative 'empeira/configuration/server_mounts'
+require_relative 'empeira/configuration/eyaml'
+require_relative 'empeira/configuration/bootstrap_guests'
+require_relative 'empeira/configuration/additional_services'
+require_relative 'empeira/configuration/service_configuration'
+require_relative 'empeira/configuration/command_mocks'
+require_relative 'empeira/configuration/dns_rewrites'
+require_relative 'empeira/configuration/network_redirects'
+require_relative 'empeira/configuration/vm_interfaces'
+require_relative 'empeira/configuration/addons'
+require_relative 'empeira/configuration/schema'
+require_relative 'empeira/configuration/ssh_preferences'
+require_relative 'empeira/configuration/user'
+require_relative 'empeira/configuration/loader'
+require_relative 'empeira/configuration/display'
+require_relative 'empeira/platform/facts'
+require_relative 'empeira/platform/resolvers'
+require_relative 'empeira/platform/locations'
+require_relative 'empeira/workspace'
+require_relative 'empeira/images/identity'
+require_relative 'empeira/vm/image_source'
+require_relative 'empeira/vm/image_cache'
+require_relative 'empeira/vm/disk'
+require_relative 'empeira/vm/root_disk'
+require_relative 'empeira/vm/qemu_runtime'
+require_relative 'empeira/vm/session_lock'
+require_relative 'empeira/vm/removal'
+require_relative 'empeira/node/ssh_credentials'
+require_relative 'empeira/node/ssh_client'
+require_relative 'empeira/node/user_ssh'
+require_relative 'empeira/node/ssh_identity'
+require_relative 'empeira/node/ssh_endpoint'
+require_relative 'empeira/vm/cloud_init'
+require_relative 'empeira/vm/guest_channel'
+require_relative 'empeira/vm/guest_output'
+require_relative 'empeira/vm/guest_shell'
+require_relative 'empeira/vm/guest_upload'
+require_relative 'empeira/vm/guest'
+require_relative 'empeira/vm/guest_network'
+require_relative 'empeira/vm/interface_ownership'
+require_relative 'empeira/vm/interface_routes'
+require_relative 'empeira/vm/interfaces'
+require_relative 'empeira/vm/certificate_runtime'
+require_relative 'empeira/execution/result'
+require_relative 'empeira/execution/console'
+require_relative 'empeira/execution/runner'
+require_relative 'empeira/execution/terminal'
+require_relative 'empeira/node/run_request'
+require_relative 'empeira/node/image'
+require_relative 'empeira/node/definition'
+require_relative 'empeira/node/certificates'
+require_relative 'empeira/node/puppet_command'
+require_relative 'empeira/node/apt_configuration'
+require_relative 'empeira/agent/target'
+require_relative 'empeira/agent/versions'
+require_relative 'empeira/agent/authentication'
+require_relative 'empeira/agent/download'
+require_relative 'empeira/agent/artifact'
+require_relative 'empeira/agent/cache_storage'
+require_relative 'empeira/agent/cache'
+require_relative 'empeira/agent/acquisition'
+require_relative 'empeira/agent/release_sources'
+require_relative 'empeira/agent/native_commands'
+require_relative 'empeira/node/agent_repository'
+require_relative 'empeira/node/dnf_agent_repository'
+require_relative 'empeira/node/agent_package'
+require_relative 'empeira/node/agent_installer'
+require_relative 'empeira/node/rpm_configuration'
+require_relative 'empeira/node/package_sources'
+require_relative 'empeira/node/runtime_proxy'
+require_relative 'empeira/node/interactive_tools'
+require_relative 'empeira/node/command_mock'
+require_relative 'empeira/node/command_mocks'
+require_relative 'empeira/node/container_bootstrap'
+require_relative 'empeira/node/vm_bootstrap'
+require_relative 'empeira/vm/bootstrap_requirements'
+require_relative 'empeira/vm/agent'
+require_relative 'empeira/node/inventory'
+require_relative 'empeira/node/container_lifecycle'
+require_relative 'empeira/node/container_preparation'
+require_relative 'empeira/node/container_agent_bootstrap'
+require_relative 'empeira/node/container_state'
+require_relative 'empeira/node/container_guest'
+require_relative 'empeira/node/container'
+require_relative 'empeira/node/vm_state'
+require_relative 'empeira/vm/management'
+require_relative 'empeira/vm/system_ssh'
+require_relative 'empeira/node/vm_preflight'
+require_relative 'empeira/node/vm_preparation'
+require_relative 'empeira/node/vm_lifecycle'
+require_relative 'empeira/node/vm'
+require_relative 'empeira/node/service'
+require_relative 'empeira/control_plane/files'
+require_relative 'empeira/control_plane/additional_configurations'
+require_relative 'empeira/modules/image'
+require_relative 'empeira/execution/diagnostics'
+require_relative 'empeira/modules/state'
+require_relative 'empeira/modules/events'
+require_relative 'empeira/modules/git_safety'
+require_relative 'empeira/modules/storage'
+require_relative 'empeira/modules/request'
+require_relative 'empeira/modules/installer'
+require_relative 'empeira/modules/host_git'
+require_relative 'empeira/addons/error'
+require_relative 'empeira/addons/manifest'
+require_relative 'empeira/addons/storage'
+require_relative 'empeira/addons/installation'
+require_relative 'empeira/addons/environment'
+require_relative 'empeira/addons/service'
+require_relative 'empeira/control_plane/environment'
+require_relative 'empeira/control_plane/browser'
+require_relative 'empeira/control_plane/plan'
+require_relative 'empeira/infrastructure/definition'
+require_relative 'empeira/infrastructure/store'
+require_relative 'empeira/infrastructure/recovery_inventory'
+require_relative 'empeira/infrastructure/owned_files'
+require_relative 'empeira/infrastructure/cleanup'
+require_relative 'empeira/infrastructure/status'
+require_relative 'empeira/control_plane/health'
+require_relative 'empeira/control_plane/storage'
+require_relative 'empeira/control_plane/discovery'
+require_relative 'empeira/control_plane/controller'
+require_relative 'empeira/infrastructure/service'
+require_relative 'empeira/updates/images'
+require_relative 'empeira/updates/modules'
+require_relative 'empeira/updates/service'
+require_relative 'empeira/application'
+
+require_relative 'empeira/platform/routes'
+require_relative 'empeira/network/peer/allocation'
+require_relative 'empeira/network/peer/backend'
+require_relative 'empeira/network/peer/channel'
+require_relative 'empeira/network/peer/channel_server'
+require_relative 'empeira/network/peer/adapter_image'
+require_relative 'empeira/network/peer/helper_security'
+require_relative 'empeira/network/peer/docker_adapter'
+require_relative 'empeira/network/peer/linux_podman'
+require_relative 'empeira/network/peer/podman_machine'
+require_relative 'empeira/network/peer/attachment'

data/resources/browser/relay.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+# Fixed destination, opaque TLS bytes: no HTTP proxy, CONNECT or routing interface.
+listener = TCPServer.new('0.0.0.0', 3001)
+loop do
+  client = listener.accept
+  Thread.new(client) do |connection|
+    address = File.read('/empeira-browser/address').strip
+    Socket.tcp(address, 3001, connect_timeout: 5) do |upstream|
+      sender = Thread.new { IO.copy_stream(connection, upstream) }
+      IO.copy_stream(upstream, connection)
+    ensure
+      sender&.kill&.join
+    end
+  rescue IOError, SystemCallError, SocketError
+    nil
+  ensure
+    connection.close
+  end
+end

data/resources/gateway/Containerfile

@@ -0,0 +1,8 @@
+ARG EMPEIRA_BASE_RUBY=library/ruby:3.4.11-alpine3.23
+FROM ${EMPEIRA_BASE_RUBY}
+RUN apk upgrade --no-cache && apk add --no-cache iproute2 iptables iptables-legacy conntrack-tools
+COPY configure.rb /usr/local/libexec/empeira-gateway
+COPY bridge.rb /usr/local/libexec/empeira-bridge
+RUN chmod 0755 /usr/local/libexec/empeira-gateway /usr/local/libexec/empeira-bridge
+ENTRYPOINT ["/usr/local/libexec/empeira-gateway"]
+CMD ["hold"]

data/resources/gateway/bridge.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+load File.join(__dir__, 'empeira-gateway') unless defined?(EmpeiraGateway)
+
+# Docker's internal bridge filtering otherwise discards off-subnet IP packets
+# even when their Ethernet destination is another peer (the workspace gateway).
+# This helper changes only two owned bridge rules, never engine chains/policies.
+module EmpeiraBridge
+  module_function
+
+  def backend
+    candidates = %w[iptables iptables-legacy].select do |binary|
+      _output, _error, status = Open3.capture3(binary, '-t', 'filter', '-S', 'DOCKER-USER')
+      status.success?
+    rescue Errno::ENOENT
+      false
+    end
+    raise 'Cannot identify Docker iptables backend; workspace remains isolated' if candidates.empty?
+
+    candidates.last
+  end
+
+  def rules(bridge, subnet, identity)
+    comment = ['-m', 'comment', '--comment', "empeira:#{identity}", '-j', 'ACCEPT']
+    [['raw', 'PREROUTING', ['-i', bridge, '-s', subnet, *comment]],
+     ['filter', 'FORWARD', ['-i', bridge, '-o', bridge, *comment]]]
+  end
+
+  def validate(action, bridge, subnet, identity)
+    raise 'Invalid workspace bridge operation' unless %w[apply remove check].include?(action)
+    unless bridge.match?(/\Aep[a-f0-9]{10}\z/) && identity.match?(/\A[a-f0-9]{64}\z/)
+      raise 'Invalid workspace bridge identity'
+    end
+    raise 'Invalid workspace subnet' unless IPAddr.new(subnet).ipv4? && IPAddr.new(subnet).prefix == 24
+    raise 'Workspace bridge is unavailable' unless File.directory?("/sys/class/net/#{bridge}/bridge")
+  end
+
+  def run(action, bridge, subnet, identity)
+    validate(action, bridge, subnet, identity)
+    binary = backend
+    rules(bridge, subnet, identity).each do |table, chain, arguments|
+      reconcile(binary, action, table, chain, arguments)
+    end
+  end
+
+  def reconcile(binary, action, table, chain, arguments)
+    _output, _error, status = Open3.capture3(binary, '--wait', '5', '-t', table, '-C', chain, *arguments)
+    raise 'Workspace bridge attachment rules missing; run empeira up' if action == 'check' && !status.success?
+
+    if action == 'apply' && !status.success?
+      EmpeiraGateway.command(binary, '--wait', '5', '-t', table, '-I', chain, '1', *arguments)
+    elsif action == 'remove' && status.success?
+      EmpeiraGateway.command(binary, '--wait', '5', '-t', table, '-D', chain, *arguments)
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    EmpeiraBridge.run(*ARGV)
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end

data/resources/gateway/configure.rb

@@ -0,0 +1,323 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'json'
+require 'open3'
+require 'socket'
+
+# Runs only inside an owned gateway or an ephemeral helper sharing one owned
+# container's network namespace. Never modifies host firewall tables or routes.
+# rubocop:disable-next Metrics/ModuleLength -- Self-contained, reviewed helper shipped in the gateway image.
+module EmpeiraGateway
+  module_function
+
+  def command(*arguments, input: nil)
+    output, error, status = Open3.capture3(*arguments, **(input ? { stdin_data: input } : {}))
+    raise "Gateway operation failed: #{arguments.first}: #{error.lines.last.to_s.strip}" unless status.success?
+
+    output
+  end
+
+  def lockdown
+    "*filter\n:INPUT DROP [0:0]\n:FORWARD DROP [0:0]\n:OUTPUT DROP [0:0]\n:BOOTSTRAP - [0:0]\nCOMMIT\n"
+  end
+
+  def restore(content)
+    command('iptables-restore', '--wait', '5', input: content)
+  end
+
+  # rubocop:disable-next Metrics/AbcSize -- Compose only explicit DNS, proxy, egress and redirect grants.
+  def rules(plan, internal:, external:)
+    filter = [':INPUT DROP [0:0]', ':FORWARD DROP [0:0]', ':OUTPUT DROP [0:0]', ':BOOTSTRAP - [0:0]',
+              "-A FORWARD -i #{internal} -o #{external} -j BOOTSTRAP"]
+    unless plan.fetch('redirects', []).empty?
+      filter << "-A FORWARD -i #{internal} -o #{internal} -m conntrack --ctstate DNAT -j BOOTSTRAP"
+    end
+    plan.fetch('blocked', []).sort.each { |ip| filter << "-A BOOTSTRAP -s #{ip}/32 -j DROP" }
+    filter.concat(redirect_filter(plan, internal))
+    filter.concat(dns_rules(plan, internal, external))
+    filter.concat(proxy_rules(plan, internal, external))
+    filter.concat(direct_rules(plan, internal, external))
+    nat = [':PREROUTING ACCEPT [0:0]', ':INPUT ACCEPT [0:0]', ':OUTPUT ACCEPT [0:0]',
+           ':POSTROUTING ACCEPT [0:0]',
+           "-A POSTROUTING -s #{plan.fetch('subnet')} -o #{external} -j MASQUERADE"]
+    nat.concat(redirect_nat(plan, internal))
+    "*filter\n#{filter.join("\n")}\nCOMMIT\n*nat\n#{nat.join("\n")}\nCOMMIT\n"
+  end
+
+  def redirect_selector(entry)
+    source = entry.fetch('from')
+    "-m conntrack --ctorigdst #{source.fetch('ip')} --ctorigdstport #{source.fetch('port')} " \
+      "--ctproto #{source.fetch('protocol', 'tcp')}"
+  end
+
+  # rubocop:disable-next Metrics/MethodLength -- Keep both conntrack directions and the final original-tuple drop together.
+  def redirect_filter(plan, internal)
+    plan.fetch('redirects', []).flat_map do |entry|
+      target = entry['to']
+      protocol = entry.fetch('from').fetch('protocol', 'tcp')
+      selector = redirect_selector(entry)
+      allowed = if target
+                  ["-A FORWARD -i #{internal} -o #{internal} -s #{plan.fetch('subnet')} " \
+                   "-d #{target.fetch('ip')}/32 -p #{protocol} --dport #{target.fetch('port')} #{selector} " \
+                   '--ctstate DNAT --ctdir ORIGINAL -j ACCEPT',
+                   "-A FORWARD -i #{internal} -o #{internal} -s #{target.fetch('ip')}/32 " \
+                   "-d #{plan.fetch('subnet')} -p #{protocol} --sport #{target.fetch('port')} #{selector} " \
+                   '--ctstate ESTABLISHED --ctdir REPLY -j ACCEPT']
+                else
+                  []
+                end
+      [*allowed, "-A FORWARD -p #{protocol} #{selector} -j DROP"]
+    end
+  end
+
+  def redirect_nat(plan, internal)
+    plan.fetch('redirects', []).filter_map do |entry|
+      target = entry['to']
+      next unless target
+
+      source = entry.fetch('from')
+      protocol = source.fetch('protocol', 'tcp')
+      ["-A PREROUTING -i #{internal} -s #{plan.fetch('subnet')} -d #{source.fetch('ip')}/32 " \
+       "-p #{protocol} --dport #{source.fetch('port')} -j DNAT " \
+       "--to-destination #{target.fetch('ip')}:#{target.fetch('port')}",
+       "-A POSTROUTING -o #{internal} -s #{plan.fetch('subnet')} -d #{target.fetch('ip')}/32 " \
+       "-p #{protocol} --dport #{target.fetch('port')} #{redirect_selector(entry)} --ctstate DNAT --ctdir ORIGINAL " \
+       "-j SNAT --to-source #{plan.fetch('gateway')}"]
+    end.flatten
+  end
+
+  def dns_rules(plan, internal, external)
+    filter = []
+    plan.fetch('resolvers').each do |ip|
+      %w[tcp udp].each do |protocol|
+        filter << "-A FORWARD -i #{internal} -o #{external} -s #{plan.fetch('dns')}/32 " \
+                  "-d #{ip}/32 -p #{protocol} --dport 53 -j ACCEPT"
+        filter << reply(internal, external, source: plan.fetch('dns'), destination: ip, port: 53, protocol: protocol)
+      end
+    end
+    filter
+  end
+
+  def proxy_rules(plan, internal, external)
+    filter = []
+    plan.fetch('proxies').each do |ip|
+      filter << "-A FORWARD -i #{internal} -o #{external} -s #{ip}/32 -p tcp " \
+                '-m multiport --dports 80,443 -j ACCEPT'
+      [80, 443].each { |port| filter << reply(internal, external, source: ip, port: port) }
+    end
+    filter
+  end
+
+  def direct_rules(plan, internal, external)
+    filter = []
+    plan.fetch('entries').each do |entry|
+      entry.fetch('addresses').each do |ip|
+        entry.fetch('ports').each do |port|
+          filter << "-A FORWARD -i #{internal} -o #{external} -s #{plan.fetch('subnet')} " \
+                    "-d #{ip}/32 -p tcp --dport #{port} -j ACCEPT"
+          filter << reply(internal, external, destination: ip, port: port)
+        end
+      end
+    end
+    filter
+  end
+
+  def reply(internal, external, port:, source: nil, destination: nil, protocol: 'tcp')
+    selector = "--ctproto #{protocol} --ctorigdstport #{port}"
+    selector += " --ctorigsrc #{source}" if source
+    selector += " --ctorigdst #{destination}" if destination
+    "-A FORWARD -i #{external} -o #{internal} -m conntrack --ctstate ESTABLISHED,RELATED #{selector} -j ACCEPT"
+  end
+
+  def ipv4(value)
+    ip = IPAddr.new(value)
+    raise 'Gateway requires explicit IPv4 addresses' unless ip.ipv4? && ip.to_s == value
+
+    value
+  end
+
+  def validate(plan)
+    raise 'Invalid gateway plan version' unless plan.fetch('version') == 1
+
+    subnet = IPAddr.new(plan.fetch('subnet'))
+    raise 'Invalid workspace subnet' unless subnet.ipv4? && subnet.private? && subnet.prefix == 24
+
+    validate_addresses(plan, subnet)
+    validate_entries(plan.fetch('entries'))
+    validate_redirects(plan.fetch('redirects', []), subnet)
+  end
+
+  def validate_redirects(entries, subnet)
+    sources = entries.map { |entry| validate_redirect(entry, subnet) }
+    raise 'Duplicate gateway redirect sources' unless sources.uniq == sources
+  end
+
+  def validate_redirect(entry, subnet)
+    raise 'Invalid gateway redirect' unless entry.is_a?(Hash) && entry.keys.sort == %w[from to]
+
+    source = entry.fetch('from')
+    validate_endpoint(source, source: true)
+    raise 'Redirect source collides with workspace subnet' if subnet.include?(source.fetch('ip'))
+
+    target = entry['to']
+    validate_redirect_target(target, source, subnet)
+    source.values_at('ip', 'port') + [source.fetch('protocol', 'tcp')]
+  end
+
+  def validate_redirect_target(target, source, subnet)
+    if target
+      validate_endpoint(target)
+      raise 'Redirect target is outside workspace subnet' unless subnet.include?(target.fetch('ip'))
+    end
+    if source.fetch('protocol', 'tcp') == 'udp' &&
+       (source.fetch('port') != 53 || (target && target.fetch('port') != 53))
+      raise 'UDP redirects require DNS port 53'
+    end
+  end
+
+  def validate_endpoint(value, source: false)
+    raise 'Invalid redirect endpoint' unless value.is_a?(Hash)
+
+    keys = source ? value.keys - ['protocol'] : value.keys
+    raise 'Invalid redirect endpoint' unless keys.sort == %w[ip port]
+    raise 'Invalid redirect protocol' if source && !%w[tcp udp].include?(value.fetch('protocol', 'tcp'))
+
+    ipv4(value.fetch('ip'))
+    validate_redirect_port(value.fetch('port'))
+  end
+
+  def validate_redirect_port(port)
+    raise 'Invalid redirect port' unless port.is_a?(Integer) && port.between?(1, 65_535)
+  end
+
+  def validate_addresses(plan, subnet)
+    %w[gateway dns].each { |key| raise 'Invalid gateway address' unless subnet.include?(ipv4(plan.fetch(key))) }
+    %w[resolvers proxies blocked].each { |key| plan.fetch(key, []).each { |ip| ipv4(ip) } }
+  end
+
+  def validate_entries(entries)
+    entries.each do |entry|
+      entry.fetch('addresses').each { |ip| ipv4(ip) }
+      valid = entry.fetch('ports').all? { |port| port.is_a?(Integer) && port.between?(1, 65_535) }
+      raise 'Invalid gateway ports' unless valid
+    end
+  end
+
+  def ipv4_interfaces
+    Socket.getifaddrs.select { |entry| entry.addr&.ipv4? && !entry.addr.ipv4_loopback? }
+  end
+
+  def interfaces(plan)
+    addresses = ipv4_interfaces
+    internal = addresses.find { |entry| entry.addr.ip_address == plan.fetch('gateway') }&.name
+    external = addresses.map(&:name).uniq.reject { |name| name == internal }
+    raise 'Gateway NAT/routing interfaces are unavailable' unless internal && external.size == 1
+
+    [internal, external.first]
+  end
+
+  def apply(path)
+    restore(lockdown)
+    plan = JSON.parse(File.binread(path))
+    validate(plan)
+    internal, external = interfaces(plan)
+    expected = rules(plan, internal: internal, external: external)
+    nat = expected.split('*nat', 2).last
+    actual = command('iptables-save')
+    if nat_configuration(actual) != nat_configuration(expected)
+      # Keep forwarding blocked until new NAT and namespace-local connection state agree.
+      restore("*nat#{nat}")
+      command('conntrack', '--flush')
+    end
+    restore(expected)
+  end
+
+  def nat_configuration(content)
+    normalized(content).select { |(table, _chain), _value| table == '*nat' }
+  end
+
+  def route(gateway)
+    ipv4(gateway)
+    interface = ipv4_interfaces.find do |entry|
+      IPAddr.new("#{entry.addr.ip_address}/24").include?(gateway)
+    end&.name
+    raise 'Workspace gateway is not on the attached subnet' unless interface
+
+    command('ip', '-4', 'route', 'flush', 'default')
+    command('ip', '-4', 'route', 'replace', 'default', 'via', gateway, 'dev', interface)
+  end
+
+  def phase(action, ip)
+    ipv4(ip)
+    arguments = ['BOOTSTRAP', '-s', "#{ip}/32", '-j', 'DROP']
+    _output, _error, exists = Open3.capture3('iptables', '--wait', '5', '-C', *arguments)
+    command('iptables', '--wait', '5', action == 'block' ? '-A' : '-D', *arguments) if
+      (action == 'block') != exists.success?
+  end
+
+  # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  def normalized(content)
+    table = nil
+    content.lines.each_with_object({}) do |line, result|
+      line = line.strip.gsub(/\[\d+:\d+\]/, '[0:0]')
+      next if line.empty? || line.start_with?('#') || line == 'COMMIT'
+
+      if line.start_with?('*')
+        table = line
+      elsif line.start_with?(':')
+        result[[table, line.split.first]] = line
+      else
+        (result[[table, line.split[1]]] ||= []) << normalized_rule(line)
+      end
+    end
+  end
+
+  def normalized_rule(line)
+    line.split.each_slice(2).filter_map do |flag, value|
+      next if flag == '-m' && %w[tcp udp].include?(value)
+
+      value = value.split(',').sort.join(',') if flag == '--ctstate'
+      value = { 'tcp' => '6', 'udp' => '17' }.fetch(value, value) if flag == '--ctproto'
+      [flag, value]
+    end.sort
+  end
+
+  def check(path)
+    plan = JSON.parse(File.binread(path))
+    validate(plan)
+    internal, external = interfaces(plan)
+    expected = rules(plan, internal: internal, external: external)
+    actual = command('iptables-save')
+    raise 'Gateway firewall drift; run empeira up' unless normalized(actual) == normalized(expected)
+    raise 'Gateway routing disabled; run empeira up' unless File.read('/proc/sys/net/ipv4/ip_forward').strip == '1'
+  end
+
+  # rubocop:disable-next Metrics/CyclomaticComplexity -- Explicit operation dispatch for the owned helper contract.
+  def run(arguments)
+    case arguments.first
+    when 'hold' then sleep
+    when 'redirects-capability'
+      command('conntrack', '--version')
+      puts 'tcp-udp-redirects-v2'
+    when 'lockdown'
+      restore(lockdown)
+    when 'apply' then apply(arguments.fetch(1))
+    when 'route' then route(arguments.fetch(1))
+    when 'block', 'unblock' then phase(*arguments)
+    when 'check'
+      check(arguments.fetch(1))
+    else raise 'Unknown gateway operation'
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    EmpeiraGateway.run(ARGV)
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end

data/resources/modules/Containerfile

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+ARG EMPEIRA_BASE_RUBY=library/ruby:3.4.11-alpine3.23
+FROM ${EMPEIRA_BASE_RUBY}
+RUN apk add --no-cache git ca-certificates
+WORKDIR /opt/empeira-modules
+COPY Gemfile Gemfile.lock ./
+RUN apk add --no-cache --virtual .build-deps build-base libffi-dev \
+    && gem install bundler -v 4.0.22 --no-document \
+    && bundle config set deployment true && bundle install --jobs 2 \
+    && apk del .build-deps
+COPY worker.rb ./
+RUN mkdir /work && chmod 1777 /work
+USER 65534:65534
+ENTRYPOINT ["ruby"]
+CMD ["-e", "sleep"]

data/resources/modules/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'r10k', '5.0.3'