ace-runtime 0.1.1 → 0.3.0

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+require "fiddle"
+
+module Ace
+  module Runtime
+    module Molecules
+      # A PID is an address, not an identity. Keep only non-secret OS facts;
+      # command lines may contain credentials and are never journaled.
+      class ProcessIdentity
+        def initialize(executor: Open3, hostname: Socket.gethostname, birth_reader: nil)
+          @executor = executor
+          @hostname = hostname
+          @birth_reader = birth_reader || method(:native_birth)
+        end
+
+        def owner(shell_pid:, caller_pid:)
+          shell = capture(shell_pid)
+          return nil unless shell && caller_pid.is_a?(Integer) && caller_pid != shell_pid
+
+          seen = []
+          observations = []
+          current = caller_pid
+          child = nil
+          64.times do
+            return nil if seen.include?(current)
+            seen << current
+            identity = capture(current)
+            return nil unless identity && identity["uid"] == shell["uid"]
+            parent = parent_pid(current)
+            return nil unless parent
+            observations << [identity, parent]
+            child = identity
+            if parent == shell_pid
+              return nil unless capture(shell_pid) == shell && observations.all? { |saved, ppid| capture(saved["pid"]) == saved && parent_pid(saved["pid"]) == ppid }
+              return {"shell_identity" => shell, "process_identity" => child}
+            end
+            current = parent
+          end
+          nil
+        end
+
+        def parent_pid(pid)
+          output, status = @executor.capture2("ps", "-p", pid.to_s, "-o", "ppid=", stdin_data: "")
+          value = output.strip
+          status.success? && value.match?(/\A[0-9]+\z/) ? value.to_i : nil
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        def capture(pid)
+          return nil unless pid.is_a?(Integer) && pid.positive?
+
+          before = @birth_reader.call(pid)
+          return nil unless before
+          output, status = @executor.capture2("ps", "-p", pid.to_s, "-o", "pid=,uid=,stat=,lstart=", stdin_data: "")
+          return nil unless status.success?
+
+          match = output.strip.match(/\A(\d+)\s+(\d+)\s+(\S+)\s+(.+)\z/)
+          return nil unless match && match[1].to_i == pid && !match[3].match?(/[ZX]/)
+
+          birth = @birth_reader.call(pid)
+          return nil unless birth && birth == before
+
+          {"pid" => pid, "uid" => match[2].to_i, "started_at" => birth, "host" => @hostname}
+        rescue SystemCallError, IOError
+          nil
+        end
+
+        # Linux start ticks are scoped to the boot; Darwin exposes microsecond
+        # process birth through libproc's documented proc_bsdinfo structure.
+        # Platforms lacking either exact facility remain unobservable.
+        def native_birth(pid)
+          if RUBY_PLATFORM.include?("linux")
+            stat = File.read("/proc/#{pid}/stat").b
+            # comm is parenthesized and may itself contain parentheses or
+            # newlines. The final closing parenthesis precedes numeric fields.
+            match = stat.match(/\A#{pid} \(.*\) ([^\n]+)\n?\z/m)
+            return nil unless match
+            fields = match[1].split
+            ticks = fields[19]
+            return nil unless fields[0]&.match?(/\A[A-Za-z]\z/) && ticks&.match?(/\A[0-9]+\z/)
+            boot = File.read("/proc/sys/kernel/random/boot_id").strip
+            return nil if boot.empty?
+            "linux:#{boot}:#{ticks}"
+          elsif RUBY_PLATFORM.include?("darwin")
+            library = Fiddle.dlopen("/usr/lib/libproc.dylib")
+            function = Fiddle::Function.new(library["proc_pidinfo"],
+              [Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_LONG_LONG, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+            buffer = Fiddle::Pointer.malloc(136)
+            return nil unless function.call(pid, 3, 0, buffer, 136) == 136
+            seconds, micros = buffer[120, 16].unpack("Q2")
+            return nil unless seconds.positive? && micros < 1_000_000
+            "darwin:#{seconds}:#{micros}"
+          end
+        rescue SystemCallError, IOError, IndexError, Fiddle::DLError
+          nil
+        end
+
+        def observe(identity)
+          at = Time.now.utc.iso8601
+          unless identity.is_a?(Hash) && identity["host"] == @hostname &&
+              identity["started_at"].is_a?(String) && identity["uid"].is_a?(Integer)
+            return {"liveness" => "unknown", "observed_at" => at, "reason" => "verified process identity unavailable"}
+          end
+
+          live = capture(identity["pid"])
+          if live == identity
+            {"liveness" => "live", "observed_at" => at, "reason" => "process identity matches", "identity" => live}
+          elsif live
+            {"liveness" => "unknown", "observed_at" => at, "reason" => "process address reused"}
+          else
+            # An inaccessible ps result cannot prove death or absence of
+            # descendants. Recovery retains the worktree and writer slot.
+            {"liveness" => "unknown", "observed_at" => at, "reason" => "process identity no longer observable"}
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "cgroup_observation"
+require_relative "../errors"
+require_relative "protected_socket"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Content evidence only. Retains every artifact and ancestor descriptor for
+      # one bounded verification, then rechecks their identities before closing.
+      class ProtectedArtifactSet
+        LIMIT = 1_048_576
+        TOTAL_LIMIT = 16 * LIMIT
+        COUNT_LIMIT = 256
+
+        class Protection
+          # These local Linux filesystems enforce POSIX mode/ACL mask semantics.
+          # Other models (including remote/FUSE filesystems) are not presumed safe.
+          FILESYSTEMS = %w[ext2 ext3 ext4 xfs btrfs tmpfs].freeze
+
+          def initialize(mounts: CgroupObservation::KernelFiles.new)
+            @mounts = mounts
+          end
+
+          def root_path!(path)
+            ProtectedSocket.root_path!(path)
+          end
+
+          def verify!(path, handle, directory:)
+            stat = handle.stat
+            unless trusted_owner?(stat) && (stat.mode & 0o022).zero? &&
+                (directory ? stat.directory? : stat.file?)
+              raise RuntimeUnavailableError, "network artifact ownership, mode or kind is unsafe"
+            end
+            unless FILESYSTEMS.include?(@mounts.mount_identity(handle).fetch("filesystem_type"))
+              raise RuntimeUnavailableError, "network artifact filesystem protection is unsupported"
+            end
+            # On these filesystems group bits are the access ACL mask: with no
+            # group/other write, no named non-root user/group can write either.
+            # Default ACLs grant no access to the existing descriptor. Every
+            # referenced file and ancestor is checked, including inherited mode.
+          end
+
+          private
+
+          def trusted_owner?(stat) = stat.uid.zero?
+        end
+
+        def initialize(protection: Protection.new, file_limit: LIMIT, total_limit: TOTAL_LIMIT, count_limit: COUNT_LIMIT)
+          unless file_limit.is_a?(Integer) && total_limit.is_a?(Integer) &&
+              file_limit.positive? && total_limit.positive? && file_limit <= total_limit
+            raise ArgumentError, "invalid protected artifact byte budgets"
+          end
+          unless count_limit.is_a?(Integer) && count_limit.positive?
+            raise ArgumentError, "invalid protected artifact count budget"
+          end
+          @protection = protection
+          @file_limit, @total_limit = file_limit, total_limit
+          @count_limit = count_limit
+        end
+
+        def with
+          @handles, @references, @contents, @total = {}, {}, {}, 0
+          yield self
+        ensure
+          @handles&.each_value { |entry| entry.fetch(:handle).close }
+          @handles = @references = @contents = nil
+        end
+
+        def read!(reference)
+          path = reference.fetch("path")
+          previous = @references[path]
+          if previous
+            raise RuntimeUnavailableError, "network artifact references conflict" unless previous == reference
+            return @contents.fetch(path)
+          end
+          raise RuntimeUnavailableError, "network artifact graph is oversized" if @references.size >= @count_limit
+          size = reference.fetch("bytes")
+          unless size.is_a?(Integer) && size.between?(1, @file_limit) && @total + size <= @total_limit
+            raise RuntimeUnavailableError, "network artifact bytes exceed bounds"
+          end
+          @protection.root_path!(path)
+          ancestors(path).reverse_each { |ancestor| pin!(ancestor, directory: true) }
+          handle = pin!(path, directory: false)
+          unless handle.stat.size == size
+            raise RuntimeUnavailableError, "network artifact declared length differs"
+          end
+          bytes = handle.read(size + 1)
+          unless bytes.is_a?(String) && bytes.bytesize == size &&
+              Digest::SHA256.hexdigest(bytes) == reference.fetch("sha256")
+            raise RuntimeUnavailableError, "network artifact content differs"
+          end
+          @references[path] = reference.dup.freeze
+          @contents[path] = bytes.freeze
+          @total += size
+          bytes
+        end
+
+        # Trusted process handoff inside the same bounded verification. The
+        # duplicate refers to the authenticated retained inode, never a reopened
+        # pathname, and is closed before this callback can outlive the set.
+        def with_readonly_handle!(reference)
+          unless @handles && @references
+            raise RuntimeUnavailableError, "protected handle requires an active verification"
+          end
+          read!(reference)
+          verify_unchanged!
+          duplicate = @handles.fetch(reference.fetch("path")).fetch(:handle).dup
+          duplicate.close_on_exec = true
+          duplicate.rewind
+          begin
+            yield duplicate
+          ensure
+            verify_unchanged!
+          end
+        ensure
+          duplicate&.close unless duplicate&.closed?
+        end
+
+        # Fixed installer entrypoints have no caller-supplied digest. Derive the
+        # reference from the same protected descriptor whose bytes are retained.
+        def read_path!(path, limit: @file_limit)
+          raise ArgumentError, "invalid artifact byte limit" unless limit.is_a?(Integer) && limit.between?(1, @file_limit)
+          raise ArgumentError, "invalid fixed artifact path" unless path.is_a?(String) &&
+            path.start_with?("/") && !path.include?("\0") && File.expand_path(path) == path
+          if @references.key?(path)
+            reference = @references.fetch(path)
+            raise RuntimeUnavailableError, "fixed artifact exceeds bounds" if reference.fetch("bytes") > limit
+            return [@contents.fetch(path), reference].freeze
+          end
+          @protection.root_path!(path)
+          ancestors(path).reverse_each { |ancestor| pin!(ancestor, directory: true) }
+          handle = pin!(path, directory: false)
+          size = handle.stat.size
+          unless size.between?(1, limit) && @references.size < @count_limit && @total + size <= @total_limit
+            raise RuntimeUnavailableError, "fixed artifact exceeds bounds"
+          end
+          bytes = handle.read(size + 1)
+          unless bytes.is_a?(String) && bytes.bytesize == size
+            raise RuntimeUnavailableError, "fixed artifact length changed"
+          end
+          reference = {"path" => path.dup.freeze, "sha256" => Digest::SHA256.hexdigest(bytes).freeze,
+            "bytes" => size}.freeze
+          if @references.key?(path)
+            raise RuntimeUnavailableError, "fixed artifact references conflict" unless @references.fetch(path) == reference
+          else
+            @references[path] = reference
+            @contents[path] = bytes.freeze
+            @total += size
+          end
+          [@contents.fetch(path), reference].freeze
+        end
+
+        def verify_unchanged!
+          @handles.each do |path, entry|
+            handle = entry.fetch(:handle)
+            unless snapshot(handle.stat, directory: entry.fetch(:directory)) == entry.fetch(:snapshot) &&
+                snapshot(File.lstat(path), directory: entry.fetch(:directory)) == entry.fetch(:snapshot)
+              raise RuntimeUnavailableError, "network artifact changed during verification"
+            end
+            @protection.verify!(path, handle, directory: entry.fetch(:directory))
+          end
+          true
+        end
+
+        private
+
+        def ancestors(path)
+          result = []
+          current = File.dirname(path)
+          loop do
+            result << current
+            break if current == "/"
+            current = File.dirname(current)
+          end
+          result
+        end
+
+        def pin!(path, directory:)
+          return @handles.fetch(path).fetch(:handle) if @handles.key?(path)
+          stat = File.lstat(path)
+          unless !stat.symlink? && (directory ? stat.directory? : stat.file?)
+            raise RuntimeUnavailableError, "network artifact kind or link is unsafe"
+          end
+          # NONBLOCK also prevents blocking if a hostile special file replaces a
+          # regular file between lstat and open; descriptor type is checked below.
+          handle = File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+          begin
+            handle.close_on_exec = true
+            @protection.verify!(path, handle, directory: directory)
+            unless snapshot(stat, directory: directory) == snapshot(handle.stat, directory: directory) && snapshot(File.lstat(path), directory: directory) == snapshot(handle.stat, directory: directory)
+              raise RuntimeUnavailableError, "network artifact changed while opening"
+            end
+            @handles[path] = {handle: handle, directory: directory, snapshot: snapshot(handle.stat, directory: directory)}
+            handle
+          rescue Exception
+            handle.close
+            raise
+          end
+        end
+
+        def snapshot(stat, directory:)
+          identity = [stat.dev, stat.ino, stat.uid, stat.gid, stat.mode]
+          directory ? identity : identity + [stat.size, stat.mtime, stat.ctime]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+require "json"
+require "socket"
+require "fiddle"
+require_relative "process_identity"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Kernel observations for protected launch. No absence inferred from ps.
+      class ProtectedLinux
+        def initialize(identity: ProcessIdentity.new)
+          @identity = identity
+        end
+
+        def supported!
+          unless RUBY_PLATFORM.include?("linux") && File.read("/proc/sys/kernel/yama/ptrace_scope").strip == "2"
+            raise RuntimeUnavailableError, "protected launch requires Linux Yama ptrace_scope=2"
+          end
+          probe = pidfd_handle(Process.pid)
+          raise RuntimeUnavailableError, "pidfd self observation is invalid" if exited?(probe)
+          true
+        rescue SystemCallError, IOError
+          raise RuntimeUnavailableError, "protected process policy is unavailable"
+        ensure
+          probe&.close
+        end
+
+        def capture(pid)
+          before = @identity.capture(pid)
+          raise RuntimeUnavailableError, "exact kernel process is unavailable" unless before
+          fields = File.readlines("/proc/#{pid}/status").to_h { |line| line.strip.split(/:\s*/, 2) }
+          ids = %w[Uid Gid].to_h { |name| [name, fields.fetch(name).split.map { |v| Integer(v, 10) }] }
+          caps = %w[CapInh CapPrm CapEff CapBnd CapAmb].to_h { |name| [name, Integer(fields.fetch(name), 16)] }
+          unless @identity.capture(pid) == before && ids.fetch("Uid").first == before.fetch("uid") && ids.values.all? { |v| v.size == 4 && v.uniq.size == 1 } &&
+              caps.values.all?(&:zero?) && fields.fetch("NoNewPrivs") == "1"
+            raise RuntimeUnavailableError, "process identity or capability policy is unsafe"
+          end
+          before.merge("gid" => ids.fetch("Gid").first,
+            "groups" => fields.fetch("Groups", "").split.map { |v| Integer(v, 10) }.sort,
+            "parent_pid" => Integer(fields.fetch("PPid"), 10))
+        rescue SystemCallError, KeyError, ArgumentError
+          raise RuntimeUnavailableError, "kernel process policy is unreadable"
+        end
+
+        def peer(socket)
+          raise RuntimeUnavailableError, "protected socket peers require Linux" unless RUBY_PLATFORM.include?("linux")
+          pid, uid, gid = socket.getsockopt(Socket::SOL_SOCKET, Socket::SO_PEERCRED).data.unpack("i!3")
+          value = capture(pid)
+          unless value["uid"] == uid && value["gid"] == gid
+            raise RuntimeUnavailableError, "socket peer changed kernel identity"
+          end
+          value
+        end
+
+        def pin(identity)
+          handle = pidfd_handle(identity.fetch("pid"))
+          begin
+            unless same?(identity, capture(identity.fetch("pid")))
+              raise RuntimeUnavailableError, "process changed while acquiring pidfd"
+            end
+            handle
+          rescue Exception
+            handle.close
+            raise
+          end
+        end
+
+        def same?(left, right)
+          %w[pid uid gid started_at host groups parent_pid].all? { |key| left[key] == right[key] }
+        end
+
+        # Socket peer ancestry, with every PID incarnation rechecked after the
+        # walk. Same UID alone never attributes a sibling to the native child.
+        def descendant?(identity, ancestor)
+          observations = []
+          current = identity.fetch("pid")
+          64.times do
+            return false if observations.any? { |item| item.fetch("pid") == current }
+            observed = capture(current)
+            return false unless observed["uid"] == ancestor["uid"]
+            return false if observations.empty? && !same?(identity, observed)
+            observations << observed
+            if current == ancestor.fetch("pid")
+              return same?(ancestor, observed) && observations.all? { |saved| same?(saved, capture(saved.fetch("pid"))) }
+            end
+            current = observed.fetch("parent_pid")
+            return false unless current.is_a?(Integer) && current.positive?
+          end
+          false
+        rescue RuntimeUnavailableError, KeyError
+          false
+        end
+
+        def live!(identity)
+          raise RuntimeUnavailableError, "exact process identity changed" unless same?(identity, capture(identity.fetch("pid")))
+          true
+        end
+
+        def exited?(handle, timeout: 0)
+          !IO.select([handle], nil, nil, timeout).nil?
+        end
+
+        private
+
+        def pidfd_handle(pid)
+          library = Fiddle.dlopen(nil)
+          call = Fiddle::Function.new(library["pidfd_open"], [Fiddle::TYPE_INT, Fiddle::TYPE_INT], Fiddle::TYPE_INT)
+          fd = call.call(pid, 0)
+          raise RuntimeUnavailableError, "exact pidfd is unavailable" if fd.negative?
+          IO.for_fd(fd, autoclose: true)
+        rescue Fiddle::DLError
+          raise RuntimeUnavailableError, "exact pidfd capability is unsupported"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+require "socket"
+require "json"
+
+module Ace
+  module Runtime
+    module Molecules
+      module ProtectedSocket
+        LIMIT = 65_536
+        # Fixed protocols that forbid descriptors use this for every control,
+        # binary-body and EOF read; rights never bypass a later framing check.
+        class Ingress
+          def initialize(socket) = @socket = socket
+          def to_io = @socket
+
+          def read_nonblock(length, exception: false)
+            result = @socket.recvmsg_nonblock(length, 0, 4096, scm_rights: true, exception: exception)
+            return result if result == :wait_readable
+            return nil if result.nil?
+            bytes, _, flags, *controls = result
+            controls.each { |control| control.unix_rights&.each(&:close) if control.cmsg_is?(Socket::SOL_SOCKET, Socket::SCM_RIGHTS) }
+            raise SecurityError, "protected ancillary input is forbidden" unless controls.empty? && (flags & Socket::MSG_CTRUNC).zero?
+            bytes.empty? ? nil : bytes
+          end
+        end
+        module_function
+
+        def root_path!(path, directory: false, owner: 0)
+          unless path.is_a?(String) && path.start_with?("/") && File.expand_path(path) == path
+            raise RuntimeUnavailableError, "protected path must be canonical and absolute"
+          end
+          current = path
+          loop do
+            stat = File.lstat(current)
+            unless !stat.symlink? && (current == path ? stat.uid == owner : [0, owner].include?(stat.uid)) && (stat.mode & 0o022).zero?
+              raise RuntimeUnavailableError, "protected path ownership or ancestry is unsafe"
+            end
+            if current != path && !stat.directory?
+              raise RuntimeUnavailableError, "protected ancestor is not a directory"
+            end
+            if current == path && directory && !stat.directory?
+              raise RuntimeUnavailableError, "protected root is not a directory"
+            end
+            break if current == "/"
+            current = File.dirname(current)
+          end
+          true
+        rescue SystemCallError
+          raise RuntimeUnavailableError, "protected path is unavailable"
+        end
+
+        def connect(path, deadline: self.deadline)
+          socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_STREAM, 0)
+          socket.close_on_exec = true
+          result = socket.connect_nonblock(Socket.sockaddr_un(path), exception: false)
+          if result == :wait_writable
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            unless remaining.positive? && IO.select(nil, [socket], nil, remaining) && socket.getsockopt(Socket::SOL_SOCKET, Socket::SO_ERROR).int.zero?
+              raise RuntimeUnavailableError, "protected socket connection deadline expired"
+            end
+          end
+          yield socket
+        ensure
+          socket&.close unless socket&.closed?
+        end
+
+        def socket_identity(path, mode: nil)
+          stat = File.lstat(path)
+          raise RuntimeUnavailableError, "protected endpoint is not a socket" unless stat.socket? && !stat.symlink?
+          if !mode.nil? && (!mode.is_a?(Integer) || !mode.between?(0, 0o7777) || (stat.mode & 0o7777) != mode)
+            raise RuntimeUnavailableError, "protected endpoint mode differs"
+          end
+          [stat.dev, stat.ino, stat.uid]
+        rescue SystemCallError
+          raise RuntimeUnavailableError, "protected endpoint is unavailable"
+        end
+
+        def read(socket, deadline:, limit: LIMIT, with_size: false)
+          buffer = +""
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise RuntimeUnavailableError, "protected socket deadline expired" unless remaining.positive? &&
+              IO.select([socket], nil, nil, remaining)
+            chunk = socket.read_nonblock(1, exception: false)
+            next if chunk == :wait_readable
+            raise RuntimeUnavailableError, "protected socket closed before response" unless chunk
+            buffer << chunk
+            raise RuntimeUnavailableError, "protected socket frame is oversized" if buffer.bytesize > limit
+            break if chunk == "\n"
+          end
+          buffer.force_encoding(Encoding::UTF_8)
+          raise RuntimeUnavailableError, "protected socket frame is malformed" unless buffer.valid_encoding?
+          value = JSON.parse(buffer, create_additions: false, max_nesting: 32,
+            allow_duplicate_key: false, allow_comments: false)
+          with_size ? {data: value, bytesize: buffer.bytesize} : value
+        rescue JSON::ParserError
+          raise RuntimeUnavailableError, "protected socket frame is malformed"
+        end
+
+        def write(socket, value, deadline:, limit: LIMIT)
+          bytes = JSON.generate(value) + "\n"
+          raise RuntimeUnavailableError, "protected socket frame is oversized" if bytes.bytesize > limit
+          until bytes.empty?
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise RuntimeUnavailableError, "protected socket deadline expired" unless remaining.positive? &&
+              IO.select(nil, [socket], nil, remaining)
+            sent = socket.write_nonblock(bytes, exception: false)
+            next if sent == :wait_writable
+            bytes = bytes.byteslice(sent..)
+          end
+        end
+
+        def deadline(seconds = 5)
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        end
+      end
+    end
+  end
+end