ace-runtime 0.1.1 → 0.3.0

data/lib/ace/runtime/molecules/systemd_scope_manager.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+require_relative "protected_socket"
+require "json"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Fixed installed system-manager units only. This adapter does not decide
+      # when a generation may start/stop: canonical lifecycle owns admission.
+      class SystemdScopeManager
+        SYSTEMCTL = "/usr/bin/systemctl"
+        BUSCTL = "/usr/bin/busctl"
+        UNIT = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
+        PROPERTIES = %w[Id LoadState ActiveState SubState InvocationID ControlGroup Job
+          FragmentPath DropInPaths].freeze
+        SERVICE_PROPERTIES = (PROPERTIES + %w[MainPID Slice]).freeze
+        UNIT_GRAPH_SIGNATURES = {
+          "Id" => "s", "Names" => "as", "LoadState" => "s", "FragmentPath" => "s", "DropInPaths" => "as",
+          "UnitFileState" => "s", "NeedDaemonReload" => "b", "StopWhenUnneeded" => "b", "DefaultDependencies" => "b",
+          **%w[Requires Requisite Wants BindsTo PartOf Upholds RequiredBy RequisiteOf WantedBy BoundBy UpheldBy
+            ConsistsOf After Before OnSuccess OnSuccessOf OnFailure OnFailureOf Triggers TriggeredBy
+            PropagatesStopTo StopPropagatedFrom JoinsNamespaceOf RequiresMountsFor WantsMountsFor].to_h { |key| [key, "as"] }
+        }.freeze
+        SERVICE_EXEC_SIGNATURES = {
+          **%w[Type User Group Restart KillMode ProtectSystem RootDirectory RootImage NetworkNamespacePath Slice StandardInput TTYPath StandardOutput StandardError WorkingDirectory RuntimeDirectoryPreserve DevicePolicy PAMName].to_h { |key| [key, "s"] },
+          **%w[SupplementaryGroups ReadWritePaths ReadOnlyPaths Environment PassEnvironment UnsetEnvironment Sockets InaccessiblePaths ExtensionDirectories RuntimeDirectory].to_h { |key| [key, "as"] },
+          **%w[SendSIGKILL Delegate ProtectControlGroups NoNewPrivileges PrivateIPC PrivateDevices DynamicUser RootEphemeral MountAPIVFS PrivateTmp ProtectKernelTunables BindLogSockets].to_h { |key| [key, "b"] },
+          **%w[CapabilityBoundingSet AmbientCapabilities RestrictNamespaces].to_h { |key| [key, "t"] },
+          "RuntimeDirectoryMode" => "u", "UMask" => "u", "RootImageOptions" => "a(ss)", "TemporaryFileSystem" => "a(ss)", "MountImages" => "a(ssba(ss))",
+          "ExtensionImages" => "a(sba(ss))", "EnvironmentFiles" => "a(sb)", "RestartForceExitStatus" => "(aiai)", "RestrictAddressFamilies" => "(bas)",
+          "DeviceAllow" => "a(ss)", "BindPaths" => "a(ssbt)", "BindReadOnlyPaths" => "a(ssbt)",
+          **%w[ExecConditionEx ExecStartPreEx ExecStartEx ExecStartPostEx ExecReloadEx ExecStopEx ExecStopPostEx].to_h { |key| [key, "a(sasasttttuii)"] }
+        }.freeze
+
+        UNIT_STATE_SIGNATURES = {"Id" => "s", "LoadState" => "s", "ActiveState" => "s", "SubState" => "s", "Job" => "(uo)"}.freeze
+        MOUNT_SIGNATURES = {"Where" => "s"}.freeze
+        ACTIVATION_UNIT_SIGNATURES = UNIT_STATE_SIGNATURES.merge("InvocationID" => "ay", "ControlGroup" => "s").freeze
+        ACTIVATION_SERVICE_SIGNATURES = {"MainPID" => "u", "ControlPID" => "u", "Slice" => "s"}.freeze
+        INBOX_CONTEXT_SIGNATURES = {"TimeoutStopUSec" => "t"}.freeze
+
+        PIDFD_ARGV = [BUSCTL, "--system", "--no-pager", "--json=short", "--auto-start=no",
+          "--allow-interactive-authorization=no", "--timeout=5", "call", "org.freedesktop.systemd1",
+          "/org/freedesktop/systemd1", "org.freedesktop.systemd1.Manager", "GetUnitByPIDFD", "h", "3"].freeze
+
+        class Command
+          LIMIT = 65_536
+
+          def call(argv, timeout:, pidfd: nil)
+            inherited = inherited_descriptor_options(argv, pidfd)
+            unless RUBY_PLATFORM.include?("linux") && File.directory?("/run/systemd/system")
+              raise RuntimeUnavailableError, "execution scope requires the Linux system systemd manager"
+            end
+            client = argv.first
+            unless [SYSTEMCTL, BUSCTL].include?(client)
+              raise RuntimeUnavailableError, "system manager client is not fixed"
+            end
+            ProtectedSocket.root_path!(client)
+            unless File.executable?(client) && (File.stat(client).mode & 0o6000).zero?
+              raise RuntimeUnavailableError, "installed system manager client is unsafe"
+            end
+            output_reader, output_writer = IO.pipe
+            error_reader, error_writer = IO.pipe
+            pid = Process.spawn({"PATH" => "/usr/bin:/bin", "LANG" => "C", "LC_ALL" => "C"}, *argv,
+              in: File::NULL, out: output_writer, err: error_writer, unsetenv_others: true, close_others: true, **inherited)
+            output_writer.close
+            error_writer.close
+            deadline = ProtectedSocket.deadline(timeout)
+            readers = [output_reader, error_reader]
+            bytes = {output_reader => +"", error_reader => +""}
+            until readers.empty?
+              remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              ready = remaining.positive? && IO.select(readers, nil, nil, remaining)
+              raise RuntimeUnavailableError, "system manager job outcome is unavailable" unless ready
+              ready.first.each do |reader|
+                chunk = reader.read_nonblock(4096, exception: false)
+                next if chunk == :wait_readable
+                if chunk.nil?
+                  readers.delete(reader)
+                else
+                  bytes.fetch(reader) << chunk
+                  if bytes.values.sum(&:bytesize) > LIMIT
+                    raise RuntimeUnavailableError, "system manager response is oversized"
+                  end
+                end
+              end
+            end
+            loop do
+              waited = Process.waitpid(pid, Process::WNOHANG)
+              if waited
+                status = $?
+                pid = nil
+                raise RuntimeUnavailableError, "fixed system manager operation was refused" unless status.success?
+                return bytes.fetch(output_reader)
+              end
+              unless Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+                raise RuntimeUnavailableError, "system manager job outcome is unavailable"
+              end
+              sleep 0.01
+            end
+          rescue SystemCallError, IOError
+            raise RuntimeUnavailableError, "system manager operation is unavailable"
+          ensure
+            [output_reader, output_writer, error_reader, error_writer].compact.each do |stream|
+              stream.close unless stream.closed?
+            end
+            if pid
+              begin
+                Process.kill("KILL", pid)
+              rescue Errno::ESRCH
+                nil
+              ensure
+                begin
+                  Process.waitpid(pid)
+                rescue Errno::ECHILD
+                  nil
+                end
+              end
+            end
+          end
+          private
+
+          def inherited_descriptor_options(argv, pidfd)
+            return {} unless pidfd || argv == PIDFD_ARGV
+            unless argv == PIDFD_ARGV && pidfd.is_a?(IO) && !pidfd.closed? && pidfd.fileno >= 3
+              raise ArgumentError, "pidfd transport requires the fixed manager method and held IO"
+            end
+            {3 => pidfd}
+          end
+        end
+
+        def initialize(slice_unit:, service_unit:, command: Command.new)
+          unless slice_unit.is_a?(String) && service_unit.is_a?(String) &&
+              UNIT.match?(slice_unit) && UNIT.match?(service_unit) &&
+              slice_unit.end_with?(".slice") && service_unit.end_with?(".service") &&
+              !%w[system.slice user.slice machine.slice].include?(slice_unit)
+            raise ArgumentError, "execution scope requires fixed dedicated slice/service units"
+          end
+          @slice_unit, @service_unit, @command = slice_unit, service_unit, command
+          @slice_ancestors = []
+          parent = slice_unit
+          loop do
+            stem = parent.delete_suffix(".slice")
+            parent = stem.include?("-") ? stem.rpartition("-").first + ".slice" : "-.slice"
+            @slice_ancestors << parent
+            break if parent == "-.slice"
+          end
+        end
+
+        # The root identity owner supplies its already policy-checked pinned
+        # lifetime. A wire descriptor number never selects this capability.
+        def unit_for_pidfd(handle:, timeout: 5)
+          unless handle.is_a?(IO) && !handle.closed?
+            raise ArgumentError, "manager identity requires a held process lifetime"
+          end
+          bytes = @command.call(PIDFD_ARGV, timeout: bounded_timeout(timeout), pidfd: handle)
+          value = strict_typed_json(bytes)
+          data = value["data"]
+          unless value.keys.sort == %w[data type] && value["type"] == "osay" &&
+              data.is_a?(Array) && data.size == 3 && data[0] == unit_object(@service_unit) &&
+              data[1] == @service_unit && invocation_bytes?(data[2]) && data[2].any?(&:positive?)
+            raise RuntimeUnavailableError, "manager lifetime belongs to another unit or invocation"
+          end
+          {"unit" => @service_unit, "invocation_id" => data[2].pack("C*").unpack1("H*")}.freeze
+        rescue JSON::ParserError, KeyError, TypeError
+          raise RuntimeUnavailableError, "typed manager lifetime response is malformed"
+        end
+
+        def inspect_units
+          slice = show(@slice_unit)
+          service = show(@service_unit, properties: SERVICE_PROPERTIES)
+          unless slice["LoadState"] == "loaded" && service["LoadState"] == "loaded" &&
+              service["Slice"] == @slice_unit
+            raise RuntimeUnavailableError, "fixed execution units are missing or their placement changed"
+          end
+          {"slice" => slice, "service" => service}
+        end
+
+        def start_slice
+          operate("start", @slice_unit)
+        end
+
+        def inspect_activation
+          inspect_units
+          slice = typed_properties(unit: @slice_unit, interface: "Unit", signatures: ACTIVATION_UNIT_SIGNATURES)
+          service = typed_properties(unit: @service_unit, interface: "Unit", signatures: ACTIVATION_UNIT_SIGNATURES)
+          service.merge!(typed_properties(unit: @service_unit, interface: "Service", signatures: ACTIVATION_SERVICE_SIGNATURES))
+          unless slice.fetch("Id") == @slice_unit && service.fetch("Id") == @service_unit &&
+              slice.fetch("LoadState") == "loaded" && service.fetch("LoadState") == "loaded" && service.fetch("Slice") == @slice_unit
+            raise RuntimeUnavailableError, "fixed activation escaped its parent slice"
+          end
+          {"slice" => slice, "service" => service}
+        end
+
+        def inspect_profile
+          # `show` loads installed metadata before typed reads; it starts no unit.
+          inspect_units
+          slice = typed_properties(unit: @slice_unit, interface: "Unit", signatures: UNIT_GRAPH_SIGNATURES)
+          service = typed_properties(unit: @service_unit, interface: "Unit", signatures: UNIT_GRAPH_SIGNATURES).merge(
+            typed_properties(unit: @service_unit, interface: "Service", signatures: SERVICE_EXEC_SIGNATURES))
+          ancestors = @slice_ancestors.to_h do |unit|
+            show(unit)
+            [unit, typed_properties(unit: unit, interface: "Unit", signatures: UNIT_GRAPH_SIGNATURES)]
+          end
+          {"slice" => slice, "service" => service, "ancestors" => ancestors, "unit_paths" => unit_paths,
+            "manager_environment" => manager_environment, "prerequisites" => inspect_prerequisites(service)}
+        end
+
+        def inspect_inbox_context_profile
+          profile = inspect_profile
+          profile.fetch("service").merge!(typed_properties(unit: @service_unit, interface: "Service",
+            signatures: INBOX_CONTEXT_SIGNATURES))
+          profile
+        end
+
+        def manager_environment(timeout: 5)
+          bytes = @command.call([BUSCTL, "--system", "--no-pager", "--json=short", "--auto-start=no",
+            "--allow-interactive-authorization=no", "get-property", "org.freedesktop.systemd1",
+            "/org/freedesktop/systemd1", "org.freedesktop.systemd1.Manager", "Environment"], timeout: bounded_timeout(timeout))
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, 65_536) && bytes.lines.size == 1
+            raise RuntimeUnavailableError, "effective manager environment is unavailable"
+          end
+          value = JSON.parse(bytes, create_additions: false, allow_duplicate_key: false, allow_comments: false, max_nesting: 4)
+          unless value.is_a?(Hash) && value.keys.sort == %w[data type] && value["type"] == "as" &&
+              value["data"].is_a?(Array) && value["data"].size <= 256 &&
+              value["data"].all? { |entry| entry.is_a?(String) && entry.bytesize.between?(1, 4096) && !entry.include?("\0") && entry.match?(/\A[A-Za-z_][A-Za-z_0-9]*=.*\z/) } &&
+              value["data"].map { |entry| entry.split("=", 2).first }.uniq.size == value["data"].size
+            raise RuntimeUnavailableError, "effective manager environment differs"
+          end
+          value.fetch("data")
+        rescue JSON::ParserError, ArgumentError
+          raise RuntimeUnavailableError, "effective manager environment is malformed"
+        end
+
+        def unit_paths
+          bytes = @command.call([BUSCTL, "--system", "--no-pager", "--json=short", "--auto-start=no",
+            "--allow-interactive-authorization=no", "get-property", "org.freedesktop.systemd1",
+            "/org/freedesktop/systemd1", "org.freedesktop.systemd1.Manager", "UnitPath"], timeout: 5)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, Command::LIMIT) && bytes.lines.size == 1
+            raise RuntimeUnavailableError, "system manager lookup paths are unavailable"
+          end
+          value = JSON.parse(bytes)
+          unless value.is_a?(Hash) && value.keys.sort == %w[data type] && value["type"] == "as" &&
+              value["data"].is_a?(Array) && value["data"].size.between?(1, 64) &&
+              value["data"].all? { |path| path.is_a?(String) && path.start_with?("/") && !path.include?("\0") && File.expand_path(path) == path }
+            raise RuntimeUnavailableError, "system manager lookup paths differ"
+          end
+          value.fetch("data")
+        rescue JSON::ParserError, KeyError
+          raise RuntimeUnavailableError, "system manager lookup paths are malformed"
+        end
+
+        # Typed reads only, against the existing system manager. Property sets
+        # and unit identities are owner-selected, never request-controlled.
+        def typed_properties(unit:, interface:, signatures:, timeout: 5)
+          unless [@slice_unit, @service_unit, *@slice_ancestors, *@prerequisite_units.to_a].include?(unit) &&
+              %w[Unit Service Mount].include?(interface) && (interface == "Unit" || interface == "Service" && unit == @service_unit || interface == "Mount" && @prerequisite_units.to_a.include?(unit) && unit.end_with?(".mount")) && signatures.is_a?(Hash) &&
+              signatures.all? { |key, value|
+                allowed = case interface
+                when "Unit" then UNIT_GRAPH_SIGNATURES.merge(ACTIVATION_UNIT_SIGNATURES)
+                when "Service" then SERVICE_EXEC_SIGNATURES.merge(ACTIVATION_SERVICE_SIGNATURES).merge(INBOX_CONTEXT_SIGNATURES)
+                when "Mount" then MOUNT_SIGNATURES
+                end
+                allowed[key] == value
+              } && !signatures.empty?
+            raise ArgumentError, "typed inspection requires fixed unit properties"
+          end
+          object = unit_object(unit)
+          bytes = @command.call([BUSCTL, "--system", "--no-pager", "--json=short", "--auto-start=no",
+            "--allow-interactive-authorization=no", "get-property", "org.freedesktop.systemd1", object,
+            "org.freedesktop.systemd1.#{interface}", *signatures.keys], timeout: bounded_timeout(timeout))
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, Command::LIMIT)
+            raise RuntimeUnavailableError, "typed manager properties are unavailable"
+          end
+          lines = bytes.lines
+          unless lines.size == signatures.size
+            raise RuntimeUnavailableError, "typed manager property set is incomplete"
+          end
+          signatures.to_a.zip(lines).to_h do |(key, signature), line|
+            value = strict_typed_json(line)
+            unless value.is_a?(Hash) && value.keys.sort == %w[data type] && value["type"] == signature && typed_value?(signature, value["data"])
+              raise RuntimeUnavailableError, "typed manager property signature differs"
+            end
+            [key, key == "InvocationID" ? value.fetch("data").pack("C*").unpack1("H*") : value.fetch("data")]
+          end
+        rescue JSON::ParserError, KeyError
+          raise RuntimeUnavailableError, "typed manager properties are malformed"
+        end
+
+        def start_service
+          operate("start", @service_unit, timeout: 45)
+        end
+
+        def stop_slice
+          operate("stop", @slice_unit)
+        end
+
+        def stop_service
+          operate("stop", @service_unit)
+        end
+
+        private
+
+        def inspect_prerequisites(service)
+          @prerequisite_units = service.values_at("Requires", "Wants", "After").flatten.uniq - [@slice_unit]
+          unless @prerequisite_units.all? { |unit| unit == "systemd-journald.socket" ||
+              unit.is_a?(String) && unit.bytesize.between?(7, 255) && unit.end_with?(".mount") && !unit.match?(/[\s\/\0]/) }
+            raise RuntimeUnavailableError, "execution service has an unverified implicit prerequisite"
+          end
+          @prerequisite_units.to_h do |unit|
+            value = typed_properties(unit: unit, interface: "Unit", signatures: UNIT_STATE_SIGNATURES)
+            value.merge!(typed_properties(unit: unit, interface: "Mount", signatures: MOUNT_SIGNATURES)) if unit.end_with?(".mount")
+            [unit, value]
+          end
+        end
+
+        def bounded_timeout(value)
+          unless value.is_a?(Numeric) && value.finite? && value.positive? && value <= 5
+            raise ArgumentError, "manager observation deadline exceeds its fixed budget"
+          end
+          value
+        end
+
+        def unit_object(unit)
+          "/org/freedesktop/systemd1/unit/" + unit.bytes.map { |byte|
+            ((byte >= 65 && byte <= 90) || (byte >= 97 && byte <= 122) || (byte >= 48 && byte <= 57)) ? byte.chr : "_%02x" % byte
+          }.join
+        end
+
+        def strict_typed_json(bytes)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, Command::LIMIT) &&
+              bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+            raise RuntimeUnavailableError, "typed manager response is unavailable"
+          end
+          value = JSON.parse(bytes, create_additions: false, max_nesting: 32,
+            allow_duplicate_key: false, allow_comments: false)
+          raise RuntimeUnavailableError, "typed manager response is malformed" unless value.is_a?(Hash)
+          value
+        end
+
+        def invocation_bytes?(value)
+          value.is_a?(Array) && value.size == 16 && value.all? { |byte| byte.is_a?(Integer) && byte.between?(0, 255) }
+        end
+
+        def typed_value?(signature, value)
+          string = ->(item) { item.is_a?(String) && !item.include?("\0") }
+          unsigned = ->(item, bits) { item.is_a?(Integer) && item >= 0 && item < (1 << bits) }
+          signed = ->(item) { item.is_a?(Integer) && item >= -(1 << 31) && item < (1 << 31) }
+          strings = ->(items) { items.is_a?(Array) && items.all? { |item| string.call(item) } }
+          case signature
+          when "ay" then invocation_bytes?(value)
+          when "s" then string.call(value)
+          when "(uo)" then value.is_a?(Array) && value.size == 2 && unsigned.call(value.first, 32) && string.call(value.last) && value.last.start_with?("/")
+          when "a(ss)"
+            value.is_a?(Array) && value.all? { |item| item.is_a?(Array) && item.size == 2 && item.all? { |part| string.call(part) } }
+          when "a(ssba(ss))", "a(sba(ss))"
+            strings_count = signature == "a(ssba(ss))" ? 2 : 1
+            value.is_a?(Array) && value.all? { |item| item.is_a?(Array) && item.size == strings_count + 2 &&
+              item.first(strings_count).all? { |part| string.call(part) } && [true, false].include?(item[strings_count]) &&
+              typed_value?("a(ss)", item.last) }
+          when "b" then value == true || value == false
+          when "t" then unsigned.call(value, 64)
+          when "u" then unsigned.call(value, 32)
+          when "as" then strings.call(value)
+          when "(aiai)"
+            value.is_a?(Array) && value.size == 2 && value.all? { |items| items.is_a?(Array) && items.all? { |item| signed.call(item) } }
+          when "(bas)"
+            value.is_a?(Array) && value.size == 2 && [true, false].include?(value.first) && strings.call(value.last)
+          when "a(sb)"
+            value.is_a?(Array) && value.all? { |item| item.is_a?(Array) && item.size == 2 && string.call(item.first) && [true, false].include?(item.last) }
+          when "a(ssbt)"
+            value.is_a?(Array) && value.all? { |item| item.is_a?(Array) && item.size == 4 &&
+              string.call(item[0]) && string.call(item[1]) && [true, false].include?(item[2]) && unsigned.call(item[3], 64) }
+          when "a(sasasttttuii)"
+            value.is_a?(Array) && value.all? { |item| item.is_a?(Array) && item.size == 10 &&
+              string.call(item[0]) && strings.call(item[1]) && strings.call(item[2]) &&
+              item[3..6].all? { |number| unsigned.call(number, 64) } && unsigned.call(item[7], 32) &&
+              signed.call(item[8]) && signed.call(item[9]) }
+          else false
+          end
+        end
+
+        def operate(verb, unit, timeout: 30)
+          @command.call([SYSTEMCTL, "--system", "--no-pager", "--no-ask-password", verb, "--", unit], timeout: timeout)
+          true
+        end
+
+        def show(unit, properties: PROPERTIES)
+          bytes = @command.call([SYSTEMCTL, "--system", "--no-pager", "--no-ask-password", "show",
+            "--all", "--property=#{properties.join(',')}", "--", unit], timeout: 5)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, Command::LIMIT)
+            raise RuntimeUnavailableError, "fixed unit properties are unavailable"
+          end
+          expected = properties
+          properties = {}
+          bytes.each_line do |line|
+            key, value = line.chomp.split("=", 2)
+            unless expected.include?(key) && value && !properties.key?(key) && !value.include?("\0")
+              raise RuntimeUnavailableError, "fixed unit property response is malformed"
+            end
+            properties[key] = value
+          end
+          unless properties.keys.sort == expected.sort && properties["Id"] == unit
+            raise RuntimeUnavailableError, "fixed system manager unit identity differs"
+          end
+          properties
+        end
+      end
+    end
+  end
+end

data/lib/ace/runtime/testing/adapter_contract.rb

@@ -43,6 +43,15 @@ module Ace
 
         # --- identity and context ---
 
+        def test_unknown_process_identity_never_grants_a_binding_or_mutates_runtime
+          pane = prepare_target!
+          before = fixture.calls.dup
+          [nil, -1, "123"].each do |pid|
+            assert_nil adapter.process_binding(pane: pane, caller_pid: pid)
+          end
+          assert_equal before, fixture.calls
+        end
+
         def test_context_reports_scripted_environment
           fixture.set_context(in_runtime: true, session: "main", window: "work", pane: "%1")
 

data/lib/ace/runtime/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Runtime
-    VERSION = "0.1.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/ace/runtime.rb

@@ -11,6 +11,9 @@ require_relative "runtime/atoms/name_sanitizer"
 require_relative "runtime/atoms/send_contract"
 require_relative "runtime/registry"
 require_relative "runtime/molecules/runtime_selector"
+require_relative "runtime/molecules/process_identity"
+require_relative "runtime/molecules/network_installation_evidence"
+require_relative "runtime/molecules/execution_network_selection"
 
 module Ace
   module Runtime

data/native/README.md

@@ -0,0 +1,124 @@
+# Protected Linux worker bootstrap
+
+The `ace-runtime` gem ships `native/worker_gate.c` and `native/build-worker-gate`.
+This is a Linux executable, not a Ruby interpreter wrapper. Build on the target
+architecture from the installed gem with the system compiler, json-c parser and OpenSSL 3 libcrypto.
+Supported initial architectures are Linux x86_64 and aarch64 with little-endian
+ELF64. A bootstrap built on another architecture fails deployment preflight.
+
+On Debian bookworm install the distribution's `build-essential`, `pkg-config`
+`libjson-c-dev` and `libssl-dev` build packages. The executable requires the matching system
+`libjson-c5`, OpenSSL 3 `libcrypto.so.3` (`libssl3`), libc and ELF loader at runtime. Use the same distribution/architecture
+for build and deployment; retain package versions, source SHA, compiler version,
+ELF machine, `readelf -d` dependencies and output SHA256 in installer evidence.
+These libraries and their loader search directories must remain root-owned and
+non-worker-writable. The pinned Herdr service starts with a clean root-controlled
+environment, so no worker loader/preload environment reaches bootstrap startup.
+
+From the installed gem directory, in a private unprivileged build directory:
+
+```sh
+native/build-worker-gate /absolute/private/build/ace-worker-gate
+sha256sum /absolute/private/build/ace-worker-gate
+readelf -h -d /absolute/private/build/ace-worker-gate
+```
+
+The administrator installs this exact artifact, without setuid/setgid bits:
+
+```sh
+install -o root -g root -m 0755 /absolute/private/build/ace-worker-gate /usr/libexec/ace-worker-gate
+```
+
+All installation ancestors are root-owned and non-worker-writable. The fixed
+root-owned `/etc/ace/assignment-authorities.json` records `bootstrap` and its exact
+`bootstrap_sha256`. ACE verifies digest, ELF architecture, executable permissions,
+ownership and ancestry before reservation. The native layout uses only this
+absolute executable, installed mapping ID and correlation ticket; cwd and environment come from the root-controlled mapping after authority release.
+The mandatory closed `worker_entry` pins interpreter and wrapper references; arbitrary
+worker argv and shebang/PATH execution are not admitted.
+The map grants no UID switching and the binary is never privileged.
+
+The root-installed authority, launcher and native server units require:
+
+```ini
+User=<their distinct mapped account>
+NoNewPrivileges=yes
+CapabilityBoundingSet=
+AmbientCapabilities=
+```
+
+Worker children inherit the server's empty bounds and no-new-privileges policy.
+ACE checks all real/effective/saved/filesystem IDs, supplementary groups, every
+capability set and `NoNewPrivs` from kernel status for all mapped participants,
+including the pinned server. CAP_DAC_OVERRIDE/CAP_SETUID are refused, as is an
+exec context that could gain capabilities or setuid privilege. Yama=2 remains
+mandatory; an empty capability set alone does not stop same-UID injection.
+
+The bootstrap sets non-dumpable before connecting, requires enforced Yama
+`ptrace_scope=2`, requires empty Inh/Prm/Eff/Bnd/Amb capability sets and NoNewPrivs=1, verifies
+worker IDs/groups and its retained actual kernel parent birth, authenticates authority
+SO_PEERCRED and protected socket ancestry, and waits at most 30 seconds on one
+stream. It never reconnects or executes after pre-release EOF, malformed input
+or timeout. A committed release whose response is lost remains potentially
+executed; public inspection must retain ownership rather than resend release.
+
+The gate accepts only the maintained `ace.assign.authorities/v2` mapping. It
+captures its actual parent PID and kernel boot/start-tick birth before reading
+the map, checks that same birth before and after parent credentials, and repeats
+the check before authority admission and immediately before exec. The canonical
+`gate_ready` authority owner associates the actual gate peer and its parent with
+the original recorded child/server; the map supplies no `server_identity`.
+Changed parent birth, reparenting, inaccessible credentials or changed policy
+refuses. The original retained mapping supplies `worker_entry={interpreter:REF,wrapper:REF}`
+in the authenticated release, rather than selecting code from the current map.
+Interpreter references are bounded to 32MiB and wrapper references to 1MiB.
+Both root-protected regular held files are hashed and their metadata rechecked.
+The interpreter must be an executable native ELF. The verified wrapper is copied
+into a memfd sealed against writes/growth/shrinkage, reopened read-only, and the
+writable descriptor dropped. Selected held interpreter FD4 and code FD5 survive
+`fexecve(4, ["/proc/self/fd/4", "-I", "-S", "-B", "/proc/self/fd/5", "authority", "worker"], env)`.
+Inherited stdin/stdout/stderr remain untouched; no provider lifetime timeout is added.
+The retained original source owner inside the wrapper separately validates and
+executes the accepted Ruby snapshot and its package closure.
+
+Release is one compact JSON record containing the original ticket/assignment/
+attempt/generation/commit plus `prepared_input`. That closed object pins the
+original registration generation/commit, definition and original binding digest,
+prepared-work reference, original worker entry pair and exact journal bundle reference/length/SHA256. The
+authority verifies the original bundle before durable issue; subsequent prepared
+fetch authenticates the accepted release pin before returning body bytes. The
+gate validates the closed ten-field pin, including the original workspace exclusion,
+digests and unchanged bounds before exec. The exclusion has five closed fields:
+key, authority UID/GID, readonly root resource and original cwd resource. Each
+resource has the existing eight identity fields. The gate checks integer/path/
+filesystem bounds and exact mapping/view/key association; the retained Ruby owner
+verifies the canonical cwd digest and held filesystem identity before acquiring
+the lifetime reader. This metadata does not itself grant filesystem access.
+The complete encoded release is bounded to16KiB before durable issue and at the gate. It
+does not receive inline work or propagate an input FD to providers. The worker
+uses the existing authenticated original prepared fetch after release.
+
+An ordinary Docker kernel with Yama=0 can verify compilation and fail-closed
+policy rejection. It cannot demonstrate protected launch acceptance. A real
+isolated Linux deployment enforcing the complete policy is required for that
+positive proof; installing this gem does not change host sysctls or install OS
+service/account policy. Downstream gad.8 provisions those requirements and
+consumes this shipped build mechanism.
+
+## Fixed digest initialization and acceptance limits
+
+Before any OpenSSL API call the gate selects `OPENSSL_INIT_NO_LOAD_CONFIG`.
+It creates a private library context, fixes its provider search path to `/dev/null`
+(a non-directory), explicitly loads only `default`, and fetches `SHA256` with
+`provider=default`. Failure refuses execution; no config/engine/module fallback
+is provided. [Initialization semantics](https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/),
+[provider search path](https://docs.openssl.org/3.0/man3/OSSL_PROVIDER/), and
+[fixed provider property](https://docs.openssl.org/3.0/man7/OSSL_PROVIDER-default/) and
+[libcrypto built-in default provider](https://docs.openssl.org/3.0/man7/crypto/#default-provider)
+are the maintained API basis. The system libcrypto/loader remain in the accepted
+root-controlled OS artifact closure; this does not attest an arbitrary library build.
+
+This source checkpoint does not compile or execute native code. Real ELF,
+OpenSSL linkage/provider availability, memfd seals, retained FD execution and
+Python script/stdlib behavior require installed Linux acceptance. The trusted
+provisioned OS/Python premise remains; no separate Python runtime tree is introduced.

data/native/build-worker-gate

@@ -0,0 +1,20 @@
+#!/bin/sh
+# Build the shipped immutable Linux bootstrap. Installation is a separate root operation.
+set -eu
+umask 077
+[ "$#" -eq 1 ] || { echo 'usage: build-worker-gate /absolute/private/output' >&2; exit 2; }
+[ "$(uname -s)" = Linux ] || { echo 'worker gate requires Linux' >&2; exit 2; }
+case "$1" in /*) ;; *) echo 'output must be absolute' >&2; exit 2;; esac
+source_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+build_dir=$(mktemp -d)
+trap 'rm -rf -- "$build_dir"' EXIT HUP INT TERM
+env -i PATH=/usr/bin:/bin /usr/bin/pkg-config --atleast-version=3.0.0 libcrypto
+env -i PATH=/usr/bin:/bin /usr/bin/pkg-config --atleast-version=0.15 json-c
+cflags=$(env -i PATH=/usr/bin:/bin /usr/bin/pkg-config --cflags json-c libcrypto)
+libs=$(env -i PATH=/usr/bin:/bin /usr/bin/pkg-config --libs json-c libcrypto)
+# pkg-config values come only from the installed system development package.
+# shellcheck disable=SC2086
+env -i PATH=/usr/bin:/bin /usr/bin/cc -std=c11 -O2 -D_FORTIFY_SOURCE=3 \
+  -fstack-protector-strong -fPIE -pie -Wl,-z,relro,-z,now \
+  -Wall -Wextra -Werror $cflags "$source_dir/worker_gate.c" $libs -o "$build_dir/ace-worker-gate"
+install -m 0755 "$build_dir/ace-worker-gate" "$1"