ace-lab 0.6.0 → 0.8.0

data/lib/ace/lab/molecules/grant_resolver.rb

@@ -64,19 +64,13 @@ module Ace
             parse_grants(content, trusted_path)
           end
 
-          private
-
-          def verify_error(path)
-            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
-              "ownership verification or could not be read; failing closed " \
-              "(required: every traversed element root-owned and not group/world-writable)"
-          end
-
-          # Read the grants document only after proving the deployment owns
-          # the storage along the original path. Genuine absence is nil
-          # (nobody authorized); every other filesystem failure — including
-          # races between lstat and open — classifies fail-closed
-          # (review rounds 6-7, F2).
+          # Read a deployment-owned file only after proving the deployment
+          # owns the storage along the original path (same trust rules as
+          # `resolve`). Genuine absence is nil; every other filesystem
+          # failure — including races between lstat and open — classifies
+          # fail-closed (review rounds 6-7, F2). Public so other trusted
+          # host-installed documents (e.g. the forge merge service identity)
+          # read through the same verification.
           # @return [String, nil] file content, or nil when absent
           def read_verified(path)
             candidate = begin
@@ -104,6 +98,14 @@ module Ace
             end
           end
 
+          private
+
+          def verify_error(path)
+            "invalid lab configuration: trusted authorization file #{path} failed the deployment " \
+              "ownership verification or could not be read; failing closed " \
+              "(required: every traversed element root-owned and not group/world-writable)"
+          end
+
           # Walk the ORIGINAL path component by component. Symlinks are
           # followed only when the link itself is root-owned (a caller-writable
           # redirect is rejected); symlink permission bits are ignored because

data/lib/ace/lab/molecules/ordinary_admission_resolver.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "service_policy"
+
+module Ace
+  module Lab
+    module Molecules
+      # The scoped ordinary-merge decision/admission resolver (spec 8x3.t.xz9.4,
+      # execution clauses). The deployment-owned YAML authorization file remains
+      # the sole source of truth; this resolver only makes the exact root
+      # authorizations natively executable inside the receiver: one per-request
+      # authorization selector resolves to a typed decision within the closed
+      # refusal-code family — or it refuses. Scoping rules:
+      #
+      # - only `operation: merge` decisions of the ordinary shape resolve;
+      #   anything else (missing reference, shape mismatch, non-merge
+      #   operation, any binding mismatch, expiry) is a typed
+      #   `ordinary_merge_authorization_invalid` decision;
+      # - exact binding match on every closed key; there are NO wildcards,
+      #   defaults, prefix grants or broad grants of any kind — a decision
+      #   authorizes exactly one bound request and nothing else;
+      # - expiry bounds the decision itself.
+      #
+      # Per-request refresh (spec 8x3.t.xz9.5 integration handoff): a
+      # long-lived receiver would otherwise decide every sequential candidate
+      # against its boot-time snapshot of the authorization document. When a
+      # trusted path is installed, every decision re-reads the document
+      # through the trusted loader and resolves against the FRESH grants —
+      # a root-revoked or expired decision fails closed at the next request
+      # without any receiver restart. The refresh is scoped: it reloads and
+      # re-validates the exact-request grant only; it never broadens
+      # authorization beyond the resolved reference.
+      class OrdinaryAdmissionResolver
+        BINDING_KEYS = ServicePolicy::ORDINARY_BINDING_KEYS.freeze
+        DECISION_KEYS = ServicePolicy::ORDINARY_AUTHORIZATION_KEYS.freeze
+        OPERATION = "merge"
+
+        Decision = Struct.new(:authorized?, :decision, :code, :message, keyword_init: true)
+
+        # @param policy_document [Hash] boot-time trusted document (the
+        #   configuration digest is derived from it once, upstream)
+        # @param path [String, nil] trusted policy path to re-read per decision
+        # @param loader [Proc, nil] trusted reader (default: GrantResolver);
+        #   the only override point, for non-privileged test documents
+        def initialize(policy_document, path: nil, loader: nil, proposal_resolver: nil, caller_uid: nil)
+          unless policy_document.is_a?(Hash) && policy_document["authorizations"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "trusted policy document must contain an authorizations mapping"
+          end
+          @authorizations = policy_document.fetch("authorizations")
+          @configuration_digest = ServicePolicy.configuration_digest(policy_document)
+          @path = path
+          @proposal_resolver = proposal_resolver
+          @caller_uid = caller_uid
+          @loader = loader || ->(trusted_path) { GrantResolver.trusted_document(trusted_path) }
+          freeze
+        end
+
+        # Resolve one authorization selector against the exact ordinary merge
+        # request binding. Returns a typed Decision; `authorized?` is true only
+        # for an exact, unexpired, ordinary-merge-shaped match.
+        def decide(reference, binding)
+          authorizations = current_authorizations
+          unless reference.is_a?(String) && reference.match?(ServicePolicy::ID)
+            return refuse("invalid authorization reference")
+          end
+          unless binding.is_a?(Hash) && binding.fetch("operation", nil) == OPERATION
+            return refuse("only the ordinary merge operation is resolvable")
+          end
+          if reference.start_with?("proposal-")
+            return refuse("canonical proposal authority is unavailable") unless @proposal_resolver && @caller_uid.is_a?(Integer)
+            begin
+              decision = @proposal_resolver.call(reference, binding.slice(
+                "operation", "project_id", "assignment_id", "attempt_id", "input_digest", "candidate_head").merge(
+                  "target" => {"resource" => binding.fetch("pr_url"), "artifact_digest" => nil},
+                  "caller_uid" => @caller_uid))
+              return Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
+            rescue Ace::Assign::Error
+              return refuse("canonical proposal does not authorize this exact ordinary merge")
+            end
+          end
+          decision = authorizations[reference]
+          return refuse("authorization reference is unresolved") unless decision.is_a?(Hash)
+          unless DECISION_KEYS.all? { |key| decision.key?(key) }
+            return refuse("authorization reference is not an ordinary merge decision")
+          end
+          unless decision.fetch("operation") == OPERATION
+            return refuse("authorization does not cover the ordinary merge operation")
+          end
+          mismatch = BINDING_KEYS.find { |key| decision.fetch(key) != binding.fetch(key, nil) }
+          return refuse("authorization does not match the exact ordinary merge request") if mismatch
+          begin
+            expired = Time.iso8601(decision.fetch("expires_at").to_s) <= Time.now.utc
+          rescue ArgumentError
+            return refuse("authorization decision has an invalid expiry")
+          end
+          return refuse("authorization has expired") if expired
+          Decision.new(authorized?: true, decision: decision, code: nil, message: nil)
+        end
+
+        private
+
+        # The authorizations mapping the CURRENT decision resolves against:
+        # the boot snapshot when no trusted path is installed, otherwise the
+        # freshly re-read document. A failed trusted re-read fails closed
+        # (InvalidConfigurationError — the unavailable family), never falls
+        # back to the stale snapshot.
+        def current_authorizations
+          return @authorizations unless @path
+          document = @loader.call(@path)
+          unless document.is_a?(Hash) && document["authorizations"].is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "invalid lab configuration: trusted authorization refresh at #{@path} " \
+              "did not yield an authorizations mapping"
+          end
+          unless ServicePolicy.configuration_digest(document) == @configuration_digest
+            raise Ace::Lab::InvalidConfigurationError,
+              "ordinary receiver configuration changed; restart with the installed configuration"
+          end
+          document.fetch("authorizations")
+        end
+
+        def refuse(message)
+          Decision.new(authorized?: false, decision: nil,
+            code: "ordinary_merge_authorization_invalid", message: message)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_listener.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require_relative "../errors"
+require_relative "ordinary_socket"
+
+module Ace
+  module Lab
+    module Molecules
+      # The ordinary receiver's serve-side transport (spec 8x3.t.xz9.4 serve
+      # entrypoint). Binds the configured unix socket and answers the exact
+      # framed protocol the OrdinarySocket client speaks: one bounded JSON
+      # document each way behind the shared handshake line. Authentication is
+      # MUTUAL through OS peer credentials: every connection's peer UID must equal
+      # the configured producer principal UID, and the listener itself runs
+      # as the configured receiver UID — the identity the client verifies on
+      # its side. Every identity, framing, deadline or parse failure is
+      # fail-closed: the peer receives the closed refusal envelope (or the
+      # connection closes) and nothing is ever dispatched. This is not an
+      # HTTP transport and there is no cross-VM fallback.
+      class OrdinaryListener
+        HANDSHAKE = OrdinarySocket::HANDSHAKE
+        LIMIT = OrdinarySocket::LIMIT
+        DEADLINE_SECONDS = 30
+
+        def initialize(socket_path:, peer_uid:, handler:, socket_gid: nil, lock_path: nil, logger: nil)
+          unless socket_path.is_a?(String) && socket_path.start_with?("/") &&
+              peer_uid.is_a?(Integer) && peer_uid >= 0 && handler.respond_to?(:call)
+            raise ArgumentError, "ordinary listener needs an absolute socket path, a peer uid and a handler"
+          end
+          unless socket_gid.nil? || (socket_gid.is_a?(Integer) && socket_gid >= 0)
+            raise ArgumentError, "ordinary listener socket_gid must be a non-negative integer"
+          end
+          @socket_gid = socket_gid
+          @socket_path = socket_path
+          @peer_uid = peer_uid
+          @handler = handler
+          @lock_path = lock_path || "#{@socket_path}.lock"
+          @logger = logger
+          @stopping = false
+        end
+
+        # Serve until #stop. Excludes a second listener through one owned
+        # lock file, removes only its own stale endpoint, and always removes
+        # the endpoint it created.
+        def serve(on_ready: nil)
+          acquire_lock!
+          remove_stale_endpoint!
+          @listener = UNIXServer.new(@socket_path)
+          @endpoint_identity = File.stat(@socket_path)
+          File.chown(nil, @socket_gid, @socket_path) if @socket_gid
+          File.chmod(@socket_gid ? 0o660 : 0o600, @socket_path)
+          on_ready.call if on_ready
+          @handler.recover_pending! if @handler.respond_to?(:recover_pending!)
+          until @stopping
+            socket = @listener.accept
+            serve_connection(socket)
+          end
+        rescue IOError, Errno::EBADF
+          raise unless @stopping
+        ensure
+          @listener&.close
+          remove_owned_endpoint!
+          @lock&.flock(File::LOCK_UN)
+          @lock&.close
+        end
+
+        # The existing listener participates in the Assign owner's lifetime.
+        def run(on_ready:)
+          serve(on_ready: on_ready)
+        end
+
+        def stop
+          @stopping = true
+          @listener&.close
+        rescue IOError
+          nil
+        end
+
+        # One bounded connection: verify the peer identity, read one framed
+        # request, answer one framed envelope, close. Fail-closed on every
+        # violation; a dispatch never happens from an unverified frame.
+        def serve_connection(socket)
+          deadline = Time.now.utc + DEADLINE_SECONDS
+          begin
+            verify_peer!(socket)
+            submission = read_request!(socket, deadline)
+            response = @handler.call(submission)
+            write_response_safely(socket, response, deadline)
+            if response.is_a?(Hash) && response["status"] == "ok" && @handler.respond_to?(:execute)
+              begin
+                # Admission is durable even if the acknowledgment was lost; the
+                # execution lifetime belongs to the canonical record, not
+                # the short connection. A lost lifecycle stays pending or
+                # uncertain and reconciles by the original reference.
+                @handler.execute(response.dig("data", "request_id"))
+              rescue StandardError => error
+                log_failure("effect", error)
+              end
+            end
+          rescue OrdinaryRefused => e
+            write_response_safely(socket, e.envelope, deadline)
+          rescue OrdinaryListenerError, IOError, SystemCallError => error
+            # Fail closed without a fabricated envelope; the client classifies
+            # a lost/unreadable response as ordinary_merge_unavailable.
+            log_failure("connection", error)
+          rescue StandardError => error
+            log_failure("request", error)
+            write_response_safely(socket, refusal_envelope("ordinary_merge_unavailable",
+              "receiver failed to handle the request"), deadline)
+          ensure
+            begin
+              socket.close
+            rescue IOError
+              nil
+            end
+          end
+        end
+
+        class OrdinaryListenerError < ::StandardError; end
+
+        # A verified-connection refusal that still carries a closed envelope.
+        class OrdinaryRefused < OrdinaryListenerError
+          attr_reader :envelope
+
+          def initialize(envelope)
+            @envelope = envelope
+            super(envelope.dig("error", "message").to_s)
+          end
+        end
+
+        private
+
+        def write_response_safely(socket, response, deadline)
+          write_response!(socket, response, deadline)
+        rescue OrdinaryListenerError, IOError, SystemCallError => error
+          log_failure("response", error)
+        end
+
+        def log_failure(phase, error)
+          # Arbitrary exception messages may contain provider credentials or
+          # request bodies. Journal references remain the source of effect state.
+          @logger&.call("ordinary receiver #{phase} failed (#{error.class.name})")
+        end
+
+        # Mutual half of OS peer authentication: the connecting process must run as the
+        # configured producer principal UID. Anything else is refused before
+        # one byte of request is read.
+        def verify_peer!(socket)
+          peer_uid, = socket.getpeereid
+          return if peer_uid == @peer_uid
+          raise OrdinaryRefused, refusal_envelope("ordinary_merge_unauthenticated",
+            "connecting principal is not the configured ordinary overseer")
+        rescue SystemCallError, IOError, SocketError, NotImplementedError
+          raise OrdinaryListenerError, "peer credentials are unavailable"
+        end
+
+        def read_request!(socket, deadline)
+          header = read_line!(socket, deadline)
+          match = /\A#{Regexp.escape(HANDSHAKE)} (\d{1,5})\n\z/o.match(header)
+          raise OrdinaryListenerError, "request header is invalid" unless match
+          length = Integer(match[1])
+          raise OrdinaryListenerError, "request exceeds the wire bound" if length > LIMIT
+          payload = read_exact!(socket, length, deadline)
+          JSON.parse(payload, allow_duplicate_key: false, create_additions: false, max_nesting: 16)
+        rescue JSON::ParserError
+          raise OrdinaryRefused, refusal_envelope("ordinary_merge_invalid_request",
+            "request document is not valid JSON")
+        end
+
+        def write_response!(socket, response, deadline)
+          payload = JSON.generate(response)
+          raise OrdinaryListenerError, "response exceeds the wire bound" if payload.bytesize > LIMIT
+          frame = "#{HANDSHAKE} #{payload.bytesize}\n#{payload}"
+          written = 0
+          while written < frame.bytesize
+            raise OrdinaryListenerError, "response write deadline expired" if Time.now.utc >= deadline
+            begin
+              written += socket.write_nonblock(frame.byteslice(written..))
+            rescue IO::WaitWritable
+              socket.wait_writable(remaining!(deadline)) or
+                raise OrdinaryListenerError, "response write deadline expired"
+            end
+          end
+        rescue JSON::GeneratorError
+          raise OrdinaryListenerError, "response is not serializable"
+        end
+
+        def refusal_envelope(code, message)
+          {"status" => "error", "error" => {
+            "schema" => "ace.lab.service.ordinary-merge-refusal/v1",
+            "code" => code,
+            "message" => message.to_s.scrub.gsub(/\s+/, " ").strip[0, 512],
+            "request_id" => "unknown",
+            "input_digest" => nil
+          }}
+        end
+
+        def read_line!(socket, deadline)
+          line = +""
+          until line.end_with?("\n")
+            raise OrdinaryListenerError, "request header is unbounded" if line.bytesize > 128
+            line << read_exact!(socket, 1, deadline)
+          end
+          line
+        end
+
+        def read_exact!(socket, length, deadline)
+          buffer = +""
+          while buffer.bytesize < length
+            raise OrdinaryListenerError, "request read deadline expired" if Time.now.utc >= deadline
+            begin
+              chunk = socket.read_nonblock(length - buffer.bytesize)
+              raise OrdinaryListenerError, "peer closed the connection" if chunk.nil?
+              buffer << chunk
+            rescue IO::WaitReadable
+              socket.wait_readable(remaining!(deadline)) or
+                raise OrdinaryListenerError, "request read deadline expired"
+            end
+          end
+          buffer
+        end
+
+        def remaining!(deadline)
+          left = deadline - Time.now.utc
+          raise OrdinaryListenerError, "connection deadline expired" if left <= 0
+          left
+        end
+
+        def acquire_lock!
+          @lock = File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+          stat = @lock.stat
+          unless stat.file? && stat.uid == Process.uid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise Ace::Lab::InvalidConfigurationError, "receiver listener lock differs"
+          end
+          unless @lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise Ace::Lab::InvalidConfigurationError, "receiver listener already active"
+          end
+        end
+
+        def remove_stale_endpoint!
+          stat = File.lstat(@socket_path)
+          unless stat.socket? && stat.uid == Process.uid
+            raise Ace::Lab::InvalidConfigurationError, "receiver endpoint differs"
+          end
+          File.unlink(@socket_path)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def remove_owned_endpoint!
+          return unless @endpoint_identity
+          stat = File.stat(@socket_path)
+          File.unlink(@socket_path) if stat.socket? && stat.ino == @endpoint_identity.ino
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_merge_read.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "ordinary_worktree_read"
+
+module Ace
+  module Lab
+    module Molecules
+      # Local checks are bounded read-only observations. Only the forge provider
+      # executes merge; moving a local ref can never prove a delivered merge.
+      class OrdinaryMergeRead
+        STRATEGY = "ff"
+
+        def initialize(repo_path:, base_ref:, root: repo_path, common_dir: File.join(repo_path, ".git"),
+          deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30)
+          unless repo_path.is_a?(String) && repo_path.start_with?("/") &&
+              base_ref.is_a?(String) && base_ref.start_with?("refs/")
+            raise ArgumentError, "ordinary merge read needs an absolute repository and full base ref"
+          end
+          @repo_path, @base_ref = repo_path, base_ref
+          @reader = OrdinaryWorktreeRead.new(root: root, common_dir: common_dir, deadline: deadline)
+        end
+
+        def base_head
+          @reader.ref_head(@repo_path, @base_ref)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        def candidate_commit?(head)
+          @reader.commit?(@repo_path, head)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        def fast_forwardable?(head)
+          @reader.ancestor?(@repo_path, base_head, head)
+        rescue Ace::Assign::Error => error
+          raise GitUnavailable, error.message
+        end
+
+        class GitUnavailable < StandardError; end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/ordinary_native_read.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ace/runtime/molecules/protected_socket"
+require "ace/herdr/molecules/herdr_executor"
+require "ace/assign/authority/ordinary_peer"
+require_relative "ordinary_owner_config"
+
+module Ace
+  module Lab
+    module Molecules
+      # Read-only use of Herdr's existing native protocol. Root selection pins
+      # the endpoint inode and live server; no ambient CLI environment chooses
+      # the daemon, and no protected runtime guarantees are borrowed here.
+      class OrdinaryNativeRead
+        def initialize(config:, deadline:, peer: Ace::Assign::Authority::OrdinaryPeer.new)
+          raise ArgumentError, "native reader needs installed selection" unless config.is_a?(OrdinaryOwnerConfig)
+          @config, @deadline, @peer = config, deadline, peer
+          @native = config.native
+        end
+
+        def preflight!
+          result = request("ping", {})
+          unless result["type"] == "pong" && result.values_at("version", "protocol") == @native.values_at("version", "protocol")
+            unavailable!("native protocol differs from installed selection")
+          end
+          true
+        end
+
+        def pane_get(pane)
+          result = request("pane.get", {"pane_id" => pane})
+          unless result["type"] == "pane_info" && result["pane"].is_a?(Hash) && result["pane"]["pane_id"] == pane
+            unavailable!("native pane metadata differs from requested pane")
+          end
+          response(result)
+        end
+
+        def pane_process_info(pane)
+          @process_info = nil
+          result = request("pane.process_info", {"pane_id" => pane})
+          unless result["type"] == "pane_process_info" && result["process_info"].is_a?(Hash) && result["process_info"]["pane_id"] == pane
+            unavailable!("native process inventory differs from requested pane")
+          end
+          @process_info = result.fetch("process_info")
+          response(result)
+        end
+
+        # This per-PID native field comes from process_cwd, not the terminal's
+        # OSC/UI working directory. The caller separately verifies PID birth.
+        def process_cwd(pid)
+          processes = @process_info.is_a?(Hash) && @process_info["foreground_processes"]
+          unavailable!("native process inventory is unavailable") unless processes.is_a?(Array)
+          matches = processes.select { |entry| entry.is_a?(Hash) && entry["pid"] == pid }
+          path = matches.one? && matches.first["cwd"]
+          unless path.is_a?(String) && path.bytesize.between?(1, 4096) && !path.include?("\0") &&
+              path.start_with?("/") && File.expand_path(path) == path
+            unavailable!("exact native process working directory is unavailable")
+          end
+          path
+        end
+
+        private
+
+        def request(method, params)
+          verify_endpoint!
+          wire.connect(@native.fetch("socket_path"), deadline: @deadline) do |socket|
+            unless @peer.capture(socket, deadline: @deadline) == @native.fetch("server_identity")
+              unavailable!("native peer differs from installed server")
+            end
+            verify_endpoint!
+            id = SecureRandom.hex(12)
+            wire.write(socket, {"id" => id, "method" => method, "params" => params}, deadline: @deadline, limit: 16_384)
+            value = wire.read(wire::Ingress.new(socket), deadline: @deadline, limit: 65_536)
+            unless value.is_a?(Hash) && value.keys.sort == %w[id result] && value["id"] == id && value["result"].is_a?(Hash)
+              unavailable!("native read response is invalid")
+            end
+            verify_endpoint!
+            @peer.live!(@native.fetch("server_identity"), deadline: @deadline)
+            value.fetch("result")
+          end
+        rescue SystemCallError, IOError, KeyError, Ace::Assign::AttemptErrors::UnauthorizedIdentity
+          unavailable!("native read is unavailable")
+        end
+
+        def verify_endpoint!
+          @config.verify_selection!
+          path = @native.fetch("socket_path")
+          wire.root_path!(File.dirname(path), directory: true)
+          unless wire.socket_identity(path) == @native.fetch("socket_identity") && (File.lstat(path).mode & 0o007).zero?
+            unavailable!("native endpoint generation or access differs")
+          end
+        end
+
+        def response(result)
+          Ace::Herdr::Molecules::ExecutionResult.new(stdout: JSON.generate({"result" => result}), stderr: "", success: true, exit_code: 0)
+        end
+
+        def wire = Ace::Runtime::Molecules::ProtectedSocket
+
+        def unavailable!(reason)
+          raise Ace::Runtime::RuntimeUnavailableError, reason
+        end
+      end
+    end
+  end
+end