ace-runtime 0.2.0 → 0.4.0

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require_relative "protected_artifact_set"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Immutable local installer input. This contains selections only; live
+      # process and resource observations must come from their owning readers.
+      class ReadinessConfiguration
+        LIMIT = 65_536
+        SCHEMA = "ace.assign.readiness/v1"
+        FIELDS = %w[authority boundary_manifest mapping_id native project_id runtime schema slot_id worker].freeze
+        attr_reader :data
+
+        def self.path(slot)
+          unless slot.is_a?(String) && slot.match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/)
+            raise RuntimeUnavailableError, "invalid readiness slot"
+          end
+          "/etc/ace/execution-slots/#{slot}/readiness.json"
+        end
+
+        def self.decode(bytes, slot:)
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          unless text.bytesize.between?(1, LIMIT) && text.valid_encoding?
+            raise RuntimeUnavailableError, "readiness configuration is not bounded UTF-8"
+          end
+          new(JSON.parse(text, create_additions: false, max_nesting: 8,
+            allow_duplicate_key: false, allow_comments: false), slot: slot)
+        rescue JSON::ParserError, EncodingError
+          raise RuntimeUnavailableError, "readiness configuration is not strict JSON"
+        end
+
+        def self.load(slot:)
+          ProtectedArtifactSet.new.with do |artifacts|
+            bytes, = artifacts.read_path!(path(slot), limit: LIMIT)
+            value = decode(bytes, slot: slot)
+            artifacts.verify_unchanged!
+            value
+          end
+        end
+
+        def initialize(data, slot:)
+          object!(data, FIELDS)
+          unless data["schema"] == SCHEMA && data["slot_id"] == slot
+            refuse!("readiness configuration selection differs")
+          end
+          %w[mapping_id project_id].each do |key|
+            refuse!("invalid readiness identifier") unless data[key].is_a?(String) &&
+              data[key].match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/)
+          end
+          object!(data.fetch("authority"), %w[gid groups socket_path uid])
+          object!(data.fetch("worker"), %w[gid groups uid])
+          %w[authority worker].each do |kind|
+            principal = data.fetch(kind)
+            unless %w[uid gid].all? { |key| principal[key].is_a?(Integer) && principal[key].positive? } &&
+                principal["groups"].is_a?(Array) && principal["groups"].all? { |gid| gid.is_a?(Integer) && gid.positive? } &&
+                principal["groups"].sort.uniq == principal["groups"]
+              refuse!("readiness principal differs")
+            end
+          end
+          native = data.fetch("native")
+          object!(native, %w[executable executable_sha256 protocol socket_path version workspace_id])
+          unless native["protocol"] == 22 && native["version"] == "0.9.3" &&
+              native["workspace_id"].is_a?(String) && native["workspace_id"].match?(/\Aw[1-9][0-9]{0,8}\z/)
+            refuse!("readiness native protocol differs")
+          end
+          digest!(native["executable_sha256"])
+          boundary = data.fetch("boundary_manifest")
+          object!(boundary, %w[path sha256])
+          unless boundary["path"] == "/etc/ace/execution-slots/#{slot}/boundary-manifest.json"
+            refuse!("readiness boundary path differs")
+          end
+          digest!(boundary["sha256"])
+          [data.dig("authority", "socket_path"), native["socket_path"], native["executable"]].each { |path| path!(path) }
+          runtime = data.fetch("runtime")
+          object!(runtime, %w[dependencies interpreter_path load_paths])
+          path!(runtime.fetch("interpreter_path"))
+          paths = runtime.fetch("load_paths")
+          unless paths.is_a?(Array) && paths.size.between?(1, 16) && paths.uniq == paths
+            refuse!("readiness load paths differ")
+          end
+          paths.each { |path| path!(path) }
+          dependencies = runtime.fetch("dependencies")
+          unless dependencies.is_a?(Array) && dependencies.size.between?(1, 256) &&
+              dependencies.map { |ref| ref.fetch("path") }.uniq.size == dependencies.size
+            refuse!("readiness dependency closure differs")
+          end
+          dependencies.each do |ref|
+            object!(ref, %w[bytes path sha256])
+            path!(ref.fetch("path"))
+            digest!(ref.fetch("sha256"))
+            unless ref["bytes"].is_a?(Integer) && ref["bytes"].between?(1, ProtectedArtifactSet::LIMIT)
+              refuse!("readiness dependency size differs")
+            end
+          end
+          @data = immutable(data)
+          freeze
+        rescue KeyError, TypeError, ArgumentError
+          refuse!("readiness configuration fields differ")
+        end
+
+        def verify_selection!(mapping_id:, mapping:, authority:, installation:)
+          expected = {"schema" => SCHEMA, "slot_id" => mapping.fetch("execution_scope").fetch("slot_id"),
+            "mapping_id" => mapping_id, "project_id" => mapping.fetch("project_id"),
+            "authority" => authority.slice("socket_path", "uid", "gid", "groups"),
+            "worker" => {"uid" => mapping.fetch("worker_uid"), "gid" => mapping.fetch("worker_gid"),
+              "groups" => mapping.fetch("worker_groups")}, "native" => mapping.fetch("native"),
+            "boundary_manifest" => {"path" => "/etc/ace/execution-slots/#{data.fetch('slot_id')}/boundary-manifest.json",
+              "sha256" => mapping.fetch("execution_scope").fetch("boundary_manifest_sha256")}, "runtime" => data.fetch("runtime")}
+          refuse!("readiness configuration does not join protected deployment") unless data == expected
+          artifacts = installation.fetch("artifacts")
+          closure = data.fetch("runtime").fetch("dependencies")
+          unless closure.all? { |ref| artifacts.any? { |artifact|
+              %w[runtime_dependency readiness_executable].include?(artifact.fetch("role")) &&
+                artifact.fetch("view_path") == ref.fetch("path") && artifact.fetch("sha256") == ref.fetch("sha256") } } &&
+              artifacts.any? { |artifact| artifact.fetch("role") == "runtime_dependency" &&
+                artifact.fetch("view_path") == data.dig("runtime", "interpreter_path") }
+            refuse!("readiness dependency closure does not join installation")
+          end
+          true
+        end
+
+        private
+
+        def object!(value, keys)
+          refuse!("readiness object fields differ") unless value.is_a?(Hash) && value.keys.sort == keys.sort
+        end
+
+        def path!(value)
+          refuse!("readiness path differs") unless value.is_a?(String) && value.bytesize.between?(2, 4096) &&
+            value.start_with?("/") && !value.include?("\0") && File.expand_path(value) == value
+        end
+
+        def digest!(value)
+          refuse!("readiness digest differs") unless value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+        end
+
+        def immutable(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.dup.freeze, immutable(item)] }.freeze
+          when Array then value.map { |item| immutable(item) }.freeze
+          when String then value.dup.freeze
+          else value
+          end
+        end
+
+        def refuse!(message) = raise(RuntimeUnavailableError, message)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+require_relative "protected_artifact_set"
+require "rbconfig"
+
+module Ace
+  module Runtime
+    module Molecules
+      # The private hook installs this guard before loading its ACE dependencies.
+      # Every executable file is verified before require can evaluate it.
+      class ReadinessRuntime
+        BUILTINS = %w[enumerator.so thread.rb fiber.so rational.so complex.so ruby2_keywords.rb].freeze
+
+        def initialize(configuration:, artifacts: ProtectedArtifactSet.new)
+          @runtime, @artifacts = configuration.fetch("runtime"), artifacts
+          @references = @runtime.fetch("dependencies").to_h { |ref| [ref.fetch("path"), ref] }.freeze
+        end
+
+        def activate!(features: $LOADED_FEATURES, load_paths: $LOAD_PATH)
+          verify_loaded!(features)
+          @runtime.fetch("load_paths").each do |path|
+            ProtectedSocket.root_path!(path, directory: true)
+          end
+          load_paths.replace(@runtime.fetch("load_paths"))
+          @initialized_builtins ||= BUILTINS.select { |feature| features.include?(feature) }.freeze
+          owner = self
+          guard = Module.new do
+            define_method(:require) do |feature|
+              return false if owner.builtin_loaded?(feature)
+              path = owner.resolve!(feature)
+              owner.verify_file!(path)
+              super(path)
+            end
+            define_method(:require_relative) do |feature|
+              caller_file = caller_locations(1, 1).first.absolute_path
+              path = owner.resolve!(File.expand_path(feature, File.dirname(caller_file)))
+              owner.verify_file!(path)
+              require(path)
+            end
+            private :require, :require_relative
+          end
+          Kernel.prepend(guard)
+          true
+        end
+
+        def verify_loaded!(features)
+          features.each do |feature|
+            next if BUILTINS.include?(feature)
+            unless feature.is_a?(String) && feature.start_with?("/") && @references.key?(feature)
+              raise RuntimeUnavailableError, "readiness startup loaded undeclared code"
+            end
+            verify_file!(feature)
+          end
+          true
+        end
+
+        def builtin_loaded?(feature)
+          return false unless feature.is_a?(String) && @initialized_builtins
+          @initialized_builtins.any? do |builtin|
+            feature == builtin || feature == builtin.sub(/\.(?:rb|so)\z/, "")
+          end
+        end
+
+        def resolve!(feature)
+          unless feature.is_a?(String) && !feature.include?("\0")
+            raise RuntimeUnavailableError, "readiness require selection differs"
+          end
+          bases = feature.start_with?("/") ? [feature] : @runtime.fetch("load_paths").map { |path| File.join(path, feature) }
+          extension = "." + RbConfig::CONFIG.fetch("DLEXT")
+          candidates = bases.flat_map do |path|
+            # Ruby maps explicit .so/.o requests to its own platform extension.
+            if path.end_with?(".so", ".o")
+              [path.sub(/\.(?:so|o)\z/, extension)]
+            elsif path.end_with?(".rb", extension)
+              [path]
+            else
+              [path, path + ".rb", path + extension]
+            end
+          end
+          selected = candidates.find { |path| @references.key?(path) }
+          raise RuntimeUnavailableError, "readiness require is outside protected closure" unless selected
+          selected
+        end
+
+        def verify_file!(path)
+          @artifacts.with do |reader|
+            reader.read!(@references.fetch(path))
+            reader.verify_unchanged!
+          end
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "rbconfig"
+require_relative "linux_mount_info"
+require_relative "../errors"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Observes declared reachable objects in a pinned server root. This does
+      # not enter or modify a namespace and carries no admission authority.
+      class ServerResourceObservation
+        VIEW_PATHS = %w[/proc /proc/sys /sys /sys/fs/cgroup /dev /dev/pts /dev/mqueue /dev/shm /tmp /var/tmp].freeze
+        MOUNT_FIELDS = %w[mount_id parent_id major_minor root mountpoint options filesystem_type].freeze
+        class Files
+          OPENAT2 = 437
+          RESOLVE = 0x10 | 0x04 # IN_ROOT | NO_SYMLINKS; bind mounts are allowed.
+
+          def supported!
+            unless RUBY_PLATFORM.include?("linux") && %w[x86_64 aarch64 arm64].include?(RbConfig::CONFIG.fetch("host_cpu"))
+              raise RuntimeUnavailableError, "contained server-root observation is unsupported"
+            end
+          end
+
+          def namespace(pid, kind = "mnt")
+            File.open("/proc/#{pid}/ns/#{kind}", File::RDONLY) { |file| identity(file.stat) }
+          end
+
+          def observe(pid, entries, authority_socket:)
+            supported!
+            root = File.open("/proc/#{pid}/root", File::RDONLY)
+            namespace = File.open("/proc/#{pid}/ns/mnt", File::RDONLY)
+            network = File.open("/proc/#{pid}/ns/net", File::RDONLY)
+            network_identity = network_identity!(network)
+            ipc = File.open("/proc/#{pid}/ns/ipc", File::RDONLY)
+            hook_ipc = File.open("/proc/self/ns/ipc", File::RDONLY)
+            root_identity, namespace_identity = identity(root.stat), identity(namespace.stat)
+            ipc_identity, hook_ipc_identity = identity(ipc.stat), identity(hook_ipc.stat)
+            table = LinuxMountInfo.new(File.read("/proc/#{pid}/mountinfo", LinuxMountInfo::LIMIT + 1))
+            raise RuntimeUnavailableError, "server mount inventory exceeds bound" if table.records.size > 256
+            topology = []
+            result = entries.map do |entry|
+              handle = open_inside(root, entry.fetch("view_path"))
+              begin
+                stat = handle.stat
+                raise RuntimeUnavailableError, "declared server resource is not a directory" unless stat.directory?
+                rows = File.read("/proc/self/fdinfo/#{handle.fileno}", 16_385).lines.filter_map do |line|
+                  /\Amnt_id:\s+([0-9]+)\s*\z/.match(line)&.[](1)
+                end
+                raise RuntimeUnavailableError, "server resource mount is ambiguous" unless rows.size == 1
+                mount = table.by_id(Integer(rows.first, 10))
+                topology << entry.slice("host_path", "view_path").merge(mount.slice("mountpoint", "root", "major_minor", "options"))
+                entry.slice("host_path", "view_path").merge("device" => stat.dev, "inode" => stat.ino,
+                  "uid" => stat.uid, "gid" => stat.gid, "filesystem_type" => mount.fetch("filesystem_type"),
+                  "mount_id" => mount.fetch("mount_id"))
+              ensure
+                handle.close
+              end
+            end
+            views = VIEW_PATHS.map { |path| pinned_view(root, path, table: table) }
+            socket_identity = pinned_socket(root, authority_socket)
+            ptmx_identity, ptmx_link = pinned_ptmx(root, table: table)
+            repeated = LinuxMountInfo.new(File.read("/proc/#{pid}/mountinfo", LinuxMountInfo::LIMIT + 1))
+            unless namespace_identity == self.namespace(pid) && root_identity == identity(File.stat("/proc/#{pid}/root")) &&
+                network_identity == self.namespace(pid, "net") &&
+                ipc_identity == self.namespace(pid, "ipc") && hook_ipc_identity == self.namespace("self", "ipc") &&
+                table.records == repeated.records &&
+                views == VIEW_PATHS.map { |path| pinned_view(root, path, table: repeated) } &&
+                socket_identity == pinned_socket(root, authority_socket) &&
+                [ptmx_identity, ptmx_link] == pinned_ptmx(root, table: repeated)
+              raise RuntimeUnavailableError, "server root or namespace changed during observation"
+            end
+            {"mount_namespace_identity" => namespace_identity, "network_namespace_identity" => network_identity, "resource_identities" => result, "resource_topology" => topology,
+              "kernel_view_topology" => {"ipc_namespace_identity" => ipc_identity, "hook_ipc_namespace_identity" => hook_ipc_identity,
+                "mounts" => table.records.map { |row| row.slice(*MOUNT_FIELDS) }, "views" => views, "authority_socket_identity" => socket_identity,
+                "ptmx_identity" => ptmx_identity, "ptmx_link" => ptmx_link}}
+          ensure
+            root&.close
+            namespace&.close
+            network&.close
+            ipc&.close
+            hook_ipc&.close
+          end
+
+          private
+
+          # NS_GET_NSTYPE is an nsfs ioctl. Pin the original server's object,
+          # require CLONE_NEWNET, and retain it across the repeated path read.
+          def network_identity!(handle)
+            unless handle.ioctl(0xb703) == 0x40000000
+              raise RuntimeUnavailableError, "server object is not a network namespace"
+            end
+            identity(handle.stat)
+          rescue SystemCallError, IOError
+            raise RuntimeUnavailableError, "server network namespace type is unavailable"
+          end
+
+          def identity(stat) = {"device" => stat.dev, "inode" => stat.ino}
+
+          def pinned_view(root, path, table:)
+            handle = open_inside(root, path, flags: 0x200000 | File::NOFOLLOW) # O_PATH, no data access.
+            stat = handle.stat
+            raise RuntimeUnavailableError, "fixed server view is not a directory" unless stat.directory?
+            rows = File.read("/proc/self/fdinfo/#{handle.fileno}", 16_385).lines.filter_map { |line| /\Amnt_id:\s+([0-9]+)\s*\z/.match(line)&.[](1) }
+            raise RuntimeUnavailableError, "fixed view mount is ambiguous" unless rows.size == 1
+            mount = table.by_id(Integer(rows.first, 10))
+            {"path" => path, "mount_id" => mount.fetch("mount_id"), "device" => stat.dev, "inode" => stat.ino, "type" => "directory"}
+          ensure
+            handle&.close
+          end
+
+          def pinned_socket(root, path)
+            handle = open_inside(root, path, flags: 0x200000 | File::NOFOLLOW)
+            stat = handle.stat
+            raise RuntimeUnavailableError, "authority projection is not a socket" unless stat.socket?
+            [stat.dev, stat.ino, stat.uid]
+          ensure
+            handle&.close
+          end
+
+          def pinned_ptmx(root, table:)
+            dev = open_inside(root, "/dev", flags: 0x200000 | File::NOFOLLOW)
+            link = read_ptmx_link(dev)
+            raise RuntimeUnavailableError, "selected ptmx link differs" unless link == "pts/ptmx"
+            node = open_inside(root, "/dev/pts/ptmx", flags: 0x200000 | File::NOFOLLOW)
+            stat = node.stat
+            raise RuntimeUnavailableError, "selected ptmx is not a character device" unless stat.chardev? && stat.rdev_major == 5 && stat.rdev_minor == 2
+            rows = File.read("/proc/self/fdinfo/#{node.fileno}", 16_385).lines.filter_map { |line| /\Amnt_id:\s+([0-9]+)\s*\z/.match(line)&.[](1) }
+            raise RuntimeUnavailableError, "selected ptmx mount is ambiguous" unless rows.size == 1
+            mount = table.by_id(Integer(rows.first, 10))
+            [{"device" => stat.dev, "inode" => stat.ino, "mount_id" => mount.fetch("mount_id"), "type" => "character",
+              "rdev_major" => stat.rdev_major, "rdev_minor" => stat.rdev_minor}, link]
+          ensure
+            dev&.close
+            node&.close
+          end
+
+          def read_ptmx_link(dev)
+            call = Fiddle::Function.new(Fiddle::Handle::DEFAULT["readlinkat"],
+              [Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T], Fiddle::TYPE_SSIZE_T)
+            buffer = Fiddle::Pointer.malloc(64)
+            count = call.call(dev.fileno, "ptmx\0", buffer, 64)
+            raise RuntimeUnavailableError, "selected ptmx link cannot be observed" unless count.between?(1, 63)
+            buffer.to_s(count)
+          end
+
+          def open_inside(root, path, flags: File::RDONLY | File::NONBLOCK | File::NOFOLLOW)
+            unless path.is_a?(String) && path.bytesize.between?(1, 4096) && path.start_with?("/") &&
+                !path.include?("\0") && File.expand_path(path) == path
+              raise RuntimeUnavailableError, "server resource path differs"
+            end
+            syscall = Fiddle::Function.new(Fiddle::Handle::DEFAULT["syscall"],
+              [Fiddle::TYPE_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],
+              Fiddle::TYPE_LONG)
+            how = [flags, 0, RESOLVE].pack("Q<Q<Q<")
+            descriptor = syscall.call(OPENAT2, root.fileno, path + "\0", how, how.bytesize)
+            raise RuntimeUnavailableError, "contained server resource cannot be opened" if descriptor.negative?
+            IO.for_fd(descriptor, autoclose: true)
+          end
+        end
+
+        def initialize(kernel:, files: Files.new)
+          @kernel, @files = kernel, files
+        end
+
+        def observe!(server:, entries:, authority_socket:)
+          @kernel.live!(server)
+          before = @kernel.capture(server.fetch("pid"))
+          unless @kernel.same?(before, server)
+            raise RuntimeUnavailableError, "server incarnation differs"
+          end
+          result = @files.observe(server.fetch("pid"), entries, authority_socket: authority_socket)
+          @kernel.live!(server)
+          unless @kernel.same?(@kernel.capture(server.fetch("pid")), before)
+            raise RuntimeUnavailableError, "server credentials changed during resource observation"
+          end
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -23,25 +23,31 @@ module Ace
             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 StandardOutput StandardError WorkingDirectory RuntimeDirectoryPreserve].to_h { |key| [key, "s"] },
+          **%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].to_h { |key| [key, "b"] },
+          **%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)",
-          "BindPaths" => "a(ssbt)", "BindReadOnlyPaths" => "a(ssbt)",
+          "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" => "s", "ControlGroup" => "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:)
+          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
@@ -56,7 +62,7 @@ module Ace
             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)
+              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)
@@ -112,6 +118,15 @@ module Ace
               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)
@@ -132,6 +147,25 @@ module Ace
           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)
@@ -168,7 +202,34 @@ module Ace
             show(unit)
             [unit, typed_properties(unit: unit, interface: "Unit", signatures: UNIT_GRAPH_SIGNATURES)]
           end
-          {"slice" => slice, "service" => service, "ancestors" => ancestors, "unit_paths" => unit_paths, "prerequisites" => inspect_prerequisites(service)}
+          {"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
@@ -191,25 +252,23 @@ module Ace
 
         # 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:)
+        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)
+                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 = "/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
+          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: 5)
+            "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
@@ -218,11 +277,11 @@ module Ace
             raise RuntimeUnavailableError, "typed manager property set is incomplete"
           end
           signatures.to_a.zip(lines).to_h do |(key, signature), line|
-            value = JSON.parse(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, value.fetch("data")]
+            [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"
@@ -255,12 +314,41 @@ module Ace
           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)"

data/lib/ace/runtime/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Runtime
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/ace/runtime.rb

@@ -13,6 +13,7 @@ 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