ace-assign 0.63.1 → 0.64.0

data/lib/ace/assign/authority/receipt_transfer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Ace
+  module Assign
+    module Authority
+      # Receipt-first binary framing. Field names come from source operations,
+      # never from the wire. Artifact order and declared digests are exact.
+      module ReceiptTransfer
+        def self.decode(input:, receipt_sha256:, artifact_field:, reference_key:)
+          unless input && input.count.between?(1, 17) && %w[artifacts evidence].include?(artifact_field) &&
+              %w[path ref].include?(reference_key) && receipt_sha256.is_a?(String) && receipt_sha256.match?(/\A[0-9a-f]{64}\z/)
+            raise AttemptErrors::ReceiptRejected, "receipt transfer binding is invalid"
+          end
+          bytes = input.bytes(index: 0)
+          unless bytes.bytesize.between?(1, 16 * 1024) && Digest::SHA256.hexdigest(bytes) == receipt_sha256
+            raise AttemptErrors::ReceiptRejected, "first transfer part must be the exact receipt"
+          end
+          receipt = JSON.parse(bytes)
+          unless receipt.is_a?(Hash) && !Models::ExecutionReceipt.forbidden_field?(receipt)
+            raise AttemptErrors::ReceiptRejected, "receipt must contain bounded structured evidence"
+          end
+          references = receipt.fetch(artifact_field)
+          unless references.is_a?(Array) && references.length == input.count - 1 && references.length <= 16 &&
+              references.all? { |entry| entry.is_a?(Hash) && entry.keys.sort == [reference_key, "sha256"].sort &&
+                entry[reference_key].is_a?(String) && entry[reference_key].bytesize.between?(1, 256) &&
+                entry["sha256"].is_a?(String) && entry["sha256"].match?(/\A[0-9a-f]{64}\z/) } &&
+              references.map { |entry| entry[reference_key] }.uniq.length == references.length
+            raise AttemptErrors::ReceiptRejected, "receipt artifact parts are incomplete or duplicated"
+          end
+          artifacts = references.each_with_index.map do |reference, index|
+            artifact = input.bytes(index: index + 1)
+            unless artifact.bytesize <= 64 * 1024 && Digest::SHA256.hexdigest(artifact) == reference.fetch("sha256")
+              raise AttemptErrors::ReceiptRejected, "receipt artifact part differs from declaration"
+            end
+            artifact
+          end
+          raise AttemptErrors::ReceiptRejected, "receipt evidence exceeds its transfer limit" if artifacts.sum(&:bytesize) > 256 * 1024
+          {receipt: receipt, artifacts: artifacts, receipt_sha256: receipt_sha256}
+        rescue JSON::ParserError, KeyError
+          raise AttemptErrors::ReceiptRejected, "receipt transfer schema is invalid"
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/authority/router.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+module Ace
+  module Assign
+    module Authority
+      # Source-owned handlers share one listener. Requests never name a method.
+      class Router
+        def initialize(launch:, handlers: [])
+          @launch = launch
+          @routes = {}
+          ([launch] + handlers).each do |handler|
+            handler.class::OPERATIONS.each do |operation|
+              raise ArgumentError, "duplicate authority operation" if @routes.key?(operation)
+              @routes[operation] = handler
+            end
+          end
+          @routes.freeze
+        end
+
+        def dispatch(request:, peer:, role:, transfer: nil)
+          handler = @routes.fetch(request.fetch("operation")) { raise ArgumentError, "unknown authority operation" }
+          options = {request: request, peer: peer, role: role}
+          options[:transfer] = transfer if transfer
+          handler.dispatch(**options)
+        end
+
+        def transfer_binding(operation)
+          handler = @routes.fetch(operation) { raise ArgumentError, "unknown authority operation" }
+          return nil unless handler.class.const_defined?(:TRANSFER_OPERATIONS, false)
+          binding = handler.class::TRANSFER_OPERATIONS[operation]
+          return nil unless binding
+          unless binding.is_a?(Hash) && binding.keys.sort == %i[direction purpose roles] &&
+              %i[upload download].include?(binding[:direction]) && TransferCodec::LIMITS.key?(binding[:purpose]) &&
+              binding[:roles].is_a?(Array) && binding[:roles].all? { |role| %i[worker launcher reviewer executor supervisor].include?(role) }
+            raise ArgumentError, "invalid source transfer binding"
+          end
+          binding
+        end
+
+        def authorize_transfer!(request:, peer:, role:)
+          handler = @routes.fetch(request.fetch("operation"))
+          handler.authorize_transfer!(request: request, peer: peer, role: role)
+        end
+
+        def close
+          @launch.close
+        end
+
+        def gate_ready(**options)
+          @launch.gate_ready(**options)
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/authority/server.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+require "socket"
+require "fileutils"
+require_relative "deployment"
+require_relative "transfer_codec"
+
+module Ace
+  module Assign
+    module Authority
+      # Existing assignment owner transport; kernel peers select roles, never argv.
+      class Server
+        CONNECTIONS = 16
+        def initialize(authority_id:, lifecycle:, deployment: Deployment.load,
+          kernel: Ace::Runtime::Molecules::ProtectedLinux.new, composition: "launch")
+          @authority_id, @lifecycle, @deployment, @kernel = authority_id, lifecycle, deployment, kernel
+          @composition = composition
+          deployment.verify_composition!(authority_id, composition: composition)
+          @service = deployment.authority(authority_id)
+          @mutex = Mutex.new
+          @connections = []
+          @handlers = []
+          @transfers = 0
+          @stopped = false
+        end
+
+        def serve
+          @kernel.supported!
+          me = @kernel.capture(Process.pid)
+          unless principal?(me, @service, "uid", "gid", "groups")
+            raise AttemptErrors::UnauthorizedIdentity, "listener principal differs from installed authority"
+          end
+          @deployment.verify_receiver_paths!(@authority_id)
+          directory = File.dirname(@service.fetch("socket_path"))
+          wire.root_path!(directory, directory: true, owner: @service.fetch("uid"))
+          lock = File.open(File.join(directory, "listener.lock"), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+          unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise AttemptErrors::Conflict, "assignment authority already owns its listener"
+          end
+          path = @service.fetch("socket_path")
+          if File.exist?(path) || File.symlink?(path)
+            raise AttemptErrors::Conflict, "existing authority endpoint requires verified installer recovery"
+          end
+          @listener = UNIXServer.new(path)
+          File.chmod(0o660, path)
+          @endpoint = wire.socket_identity(path)
+          until @stopped
+            ready = IO.select([@listener], nil, nil, 0.25)
+            next unless ready
+            socket = @listener.accept_nonblock(exception: false)
+            next if socket == :wait_readable
+            admitted = @mutex.synchronize do
+              if @connections.size < CONNECTIONS
+                @connections << socket
+                true
+              end
+            end
+            unless admitted
+              refusal(socket, "busy")
+              socket.close
+              next
+            end
+            @mutex.synchronize do
+              @handlers.reject! { |handler| !handler.alive? }
+              @handlers << Thread.new(socket) { |connection| receive(connection) }
+            end
+          end
+        rescue IOError, Errno::EBADF
+          raise unless @stopped
+        ensure
+          stop
+          # Closing a stream does not cancel a handler already inside dispatch.
+          # The owner lock and endpoint remain held until every handler ends.
+          @mutex.synchronize { @handlers.dup }.each(&:join)
+          @lifecycle.close if @endpoint && @lifecycle.respond_to?(:close)
+          if @endpoint && same_endpoint?(path)
+            File.unlink(path)
+          end
+          lock&.close
+        end
+
+        def request_stop
+          @stopped = true
+        end
+
+        def stop
+          @stopped = true
+          @listener&.close unless @listener&.closed?
+          @mutex.synchronize { @connections.each { |socket| socket.close unless socket.closed? } }
+        end
+
+        private
+
+        def same_endpoint?(path)
+          wire.socket_identity(path) == @endpoint
+        rescue StandardError
+          false
+        end
+
+        def receive(socket)
+          deadline = wire.deadline(30)
+          peer = @kernel.peer(socket)
+          frame = wire.read(socket, deadline: [deadline, wire.deadline(5)].min, with_size: true)
+          request = frame.fetch(:data)
+          unless request.is_a?(Hash) && request.keys.sort == %w[mutation_id operation params project_id version] &&
+              request["version"] == 1 && request["operation"].is_a?(String) && request["params"].is_a?(Hash)
+            raise ArgumentError, "invalid authority envelope"
+          end
+          deadline = wire.deadline(90) if %w[reserve_attempt close_execution_scope].include?(request.fetch("operation"))
+          params = request.fetch("params")
+          map = @deployment.verify!(params.fetch("mapping_id"), kernel: @kernel, authority_state: true)
+          unless map["authority_id"] == @authority_id && map["project_id"] == request["project_id"]
+            raise AttemptErrors::UnauthorizedIdentity, "mapping belongs to another authority or project"
+          end
+          role = if principal?(peer, map, "launcher_uid", "launcher_gid", "launcher_groups")
+            :launcher
+          elsif principal?(peer, map, "worker_uid", "worker_gid", "worker_groups")
+            :worker
+          end
+          unless role
+            project = @deployment.project(map.fetch("project_id"))
+            configured = project.fetch("peer_credentials")[peer.fetch("uid").to_s]
+            if configured && peer["gid"] == configured["gid"] && peer["groups"] == configured["groups"]
+              {reviewer: "reviewer_uids", executor: "service_executor_uids", supervisor: "supervisor_uids"}.each do |candidate, key|
+                role ||= candidate if project.fetch(key).include?(peer.fetch("uid"))
+              end
+            end
+          end
+          raise AttemptErrors::UnauthorizedIdentity, "unmapped kernel peer" unless role
+          if %w[observe_execution_scope close_execution_scope].include?(request["operation"]) ||
+              @composition == "services" && %w[attempt_status evidence_fetch].include?(request["operation"])
+            bodyless_read!(socket, deadline)
+          end
+          if request["operation"] == "gate_ready"
+            raise AttemptErrors::UnauthorizedIdentity, "gate readiness requires worker peer" unless role == :worker
+            @lifecycle.gate_ready(request: request, peer: peer, socket: socket, deadline: deadline)
+          else
+            binding = @lifecycle.transfer_binding(request.fetch("operation")) if @lifecycle.respond_to?(:transfer_binding)
+            if binding
+              raise AttemptErrors::UnauthorizedIdentity, "transfer role differs" unless binding.fetch(:roles).include?(role)
+              raise ArgumentError, "transfer control header is oversized" if frame.fetch(:bytesize) > 16_384
+              @lifecycle.authorize_transfer!(request: request, peer: peer, role: role)
+              admitted_transfer = @mutex.synchronize do
+                if @transfers < 2
+                  @transfers += 1
+                  true
+                end
+              end
+              raise AttemptErrors::Conflict, "transfer capacity is busy" unless admitted_transfer
+              codec = transfer_codec
+              if binding.fetch(:direction) == :upload
+                result = codec.receive(socket, descriptor: params.fetch("transfer"), purpose: binding.fetch(:purpose), deadline: deadline) do |input|
+                  @lifecycle.dispatch(request: request, peer: peer, role: role, transfer: input)
+                end
+              else
+                result = @lifecycle.dispatch(request: request, peer: peer, role: role)
+                parts = result.fetch(:transfer_parts)
+                descriptor = codec.descriptor(parts, purpose: binding.fetch(:purpose))
+                result = result.merge(data: result.fetch(:data).merge("transfer" => descriptor))
+              end
+            else
+              raise ArgumentError, "unexpected transfer descriptor" if params.key?("transfer")
+              result = @lifecycle.dispatch(request: request, peer: peer, role: role)
+            end
+            wire.write(socket, {"status" => "ok", "data" => result.fetch(:data),
+              "transport" => {"replayed" => result.fetch(:replayed, false)}}, deadline: deadline, limit: 16_384)
+            if binding && binding.fetch(:direction) == :download
+              codec.send(socket, parts: parts, descriptor: descriptor, purpose: binding.fetch(:purpose), deadline: deadline)
+            end
+          end
+        rescue ArgumentError, KeyError, AttemptErrors::MalformedTransfer
+          refusal(socket, "invalid_input")
+        rescue AttemptErrors::UnauthorizedIdentity
+          refusal(socket, "unauthorized")
+        rescue AttemptErrors::Conflict
+          refusal(socket, "conflict")
+        rescue AttemptErrors::NotFound
+          refusal(socket, "missing")
+        rescue StandardError
+          refusal(socket, "evidence_unavailable")
+        ensure
+          socket.close unless socket.closed?
+          @mutex.synchronize do
+            @connections.delete(socket)
+            @transfers -= 1 if admitted_transfer
+          end
+        end
+
+        # These closed read operations have no request body. Half-close proves
+        # framing completion before status or artifact data can be exposed.
+        def bodyless_read!(socket, deadline)
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise ArgumentError, "read request framing is incomplete" unless remaining.positive? && IO.select([socket], nil, nil, remaining)
+            bytes = socket.read_nonblock(1, exception: false)
+            next if bytes == :wait_readable
+            raise ArgumentError, "unexpected read request body" unless bytes.nil?
+            return
+          end
+        end
+
+        def transfer_codec
+          @mutex.synchronize do
+            @transfer_codec ||= begin
+              root = @service.fetch("state_root")
+              PrivateDirectory.verify!(root)
+              spool = File.join(root, "transfers")
+              Dir.mkdir(spool, 0o700) unless File.exist?(spool) || File.symlink?(spool)
+              TransferCodec.new(root: spool)
+            end
+          end
+        end
+
+        def principal?(identity, mapping, uid, gid, groups)
+          identity["uid"] == mapping[uid] && identity["gid"] == mapping[gid] && identity["groups"] == mapping[groups]
+        end
+
+        def refusal(socket, code)
+          wire.write(socket, {"status" => "error", "error" => {"code" => code, "message" => "Protected authority refused #{code}"}},
+            deadline: wire.deadline(0.1))
+        rescue StandardError
+          nil
+        end
+
+        def wire
+          Ace::Runtime::Molecules::ProtectedSocket
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/authority/service_evidence.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/canonical_evidence"
+
+module Ace
+  module Assign
+    module Authority
+      # One source-owned context for initial and retained service evidence.
+      # The journal supplies the record and transient pending view; callers
+      # never supply an alternate reader, artifact path or trusted flag.
+      class ServiceEvidence
+        FIELDS = (Molecules::EvidenceJournal::TERMINAL_BINDING_FIELDS +
+          %w[dispatch_ticket_id claim_binding candidate_generation claim_generation policy_digest]).freeze
+
+        def initialize(journal:)
+          @journal = journal
+          @canonical = Molecules::CanonicalEvidence.new(journal: journal)
+        end
+
+        def context(record, no_effect: false)
+          binding = FIELDS.to_h { |key| [key, record.fetch(key)] }
+          unless %w[claim_binding policy_digest].all? { |key| binding[key].is_a?(String) && binding[key].match?(/\A[0-9a-f]{64}\z/) } &&
+              %w[candidate_generation claim_generation].all? { |key| binding[key].is_a?(Integer) && binding[key].positive? } &&
+              binding["dispatch_ticket_id"].is_a?(String) && binding["dispatch_ticket_id"].match?(Molecules::JournalMutation::ID)
+            raise AttemptErrors::EvidenceUnavailable, "canonical dispatch binding is invalid"
+          end
+          if no_effect
+            binding.merge!(%w[no_effect_challenge challenge_generation challenge_event_digest].to_h do |key|
+              [key, record.fetch(key)]
+            end)
+            unless binding["no_effect_challenge"].is_a?(String) && !binding["no_effect_challenge"].empty? &&
+                binding["challenge_generation"].is_a?(Integer) && binding["challenge_generation"].positive? &&
+                binding["challenge_event_digest"].is_a?(String) && binding["challenge_event_digest"].match?(/\A[0-9a-f]{64}\z/)
+              raise AttemptErrors::EvidenceUnavailable, "canonical no-effect challenge is invalid"
+            end
+          end
+          {kind: "service", project_id: record.fetch("project_id"), assignment_id: record.fetch("assignment_id"),
+            attempt_id: record.fetch("attempt_id"), peer_uid: record.fetch("executor_uid"), binding: binding,
+            request_id_or_event_id: record.fetch("request_id"), generation: record.fetch("claim_generation")}
+        rescue KeyError
+          raise AttemptErrors::EvidenceUnavailable, "canonical service evidence binding is incomplete"
+        end
+
+        def call(reference, record, state, pending)
+          expected = context(record, no_effect: state == "failed-settled")
+          if pending && pending[:pending_events]
+            @canonical.read_pending(reference, **expected, **pending.slice(:current_events, :pending_events, :blobs, :commit))
+          else
+            @canonical.read(reference, **expected, commit: pending && pending[:commit] || @journal.ref_value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/authority/transfer_codec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tempfile"
+require "timeout"
+require_relative "private_directory"
+
+module Ace
+  module Assign
+    module Authority
+      # Binary framing after the existing authenticated control header. The
+      # Server selects purpose from a source handler's fixed operation table,
+      # admits a transfer slot before calling, and holds no journal lock here.
+      class TransferCodec
+        LIMITS = {candidate: [64 * 1024 * 1024, 1, 64 * 1024 * 1024],
+                  artifacts: [256 * 1024, 16, 64 * 1024],
+                  receipt_artifacts: [272 * 1024, 17, 64 * 1024],
+                  service_input: [64 * 1024, 1, 64 * 1024],
+                  inbox_proof: [32 * 1024, 2, 16 * 1024]}.freeze
+        SHA256 = /\A[0-9a-f]{64}\z/
+
+        class Input
+          def initialize(file, descriptor)
+            @file, @descriptor = file, descriptor
+          end
+
+          def bytes(index: 0)
+            unless index.is_a?(Integer) && index.between?(0, count - 1)
+              raise ArgumentError, "Invalid transferred part index"
+            end
+            part = @descriptor.fetch("parts").fetch(index)
+            offset = @descriptor.fetch("parts").take(index).sum { |entry| entry.fetch("bytes") }
+            @file.seek(offset)
+            bytes = (@file.read(part.fetch("bytes")) || "").b
+            unless bytes.bytesize == part["bytes"] && Digest::SHA256.hexdigest(bytes) == part["sha256"]
+              raise AttemptErrors::ReceiptRejected, "Transferred bytes no longer match accepted binding"
+            end
+            bytes
+          end
+
+          def count
+            @descriptor.fetch("parts").length
+          end
+        end
+
+        def initialize(root:)
+          @root = PrivateDirectory.verify!(root)
+        end
+
+        # Upload write-EOF is required before invoking the mutation consumer.
+        # Persistent launch gate connections never use this codec.
+        def receive(socket, descriptor:, purpose:, deadline:)
+          validate!(descriptor, purpose)
+          descriptor = descriptor.merge("parts" => descriptor.fetch("parts").map { |part| part.dup.freeze }.freeze).freeze
+          deadline = [deadline, Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30].min
+          PrivateDirectory.verify!(@root)
+          Tempfile.create(["transfer-", ".bytes"], @root, binmode: true) do |file|
+            digest = Digest::SHA256.new
+            descriptor.fetch("parts").each do |part|
+              part_digest = Digest::SHA256.new
+              remaining = part.fetch("bytes")
+              while remaining.positive?
+                chunk = read(socket, [remaining, 65_536].min, deadline)
+                reject!("Transferred bytes ended early") if chunk.nil?
+                file.write(chunk)
+                digest.update(chunk)
+                part_digest.update(chunk)
+                remaining -= chunk.bytesize
+              end
+              reject!("Transferred part digest differs") unless part_digest.hexdigest == part["sha256"]
+            end
+            reject!("Transferred aggregate digest differs") unless digest.hexdigest == descriptor["sha256"]
+            reject!("Transferred bytes exceed declared size") unless read(socket, 1, deadline).nil?
+            file.flush
+            file.rewind
+            yield Input.new(file, descriptor)
+          end
+        end
+
+        def descriptor(parts, purpose:)
+          reject!("Invalid transfer parts") unless parts.is_a?(Array) && parts.all? { |part| part.is_a?(String) }
+          digest = Digest::SHA256.new
+          parts.each { |part| digest.update(part.b) }
+          result = {"version" => 1, "bytes" => parts.sum(&:bytesize), "sha256" => digest.hexdigest,
+                    "parts" => parts.map { |part| {"bytes" => part.bytesize, "sha256" => Digest::SHA256.hexdigest(part.b)} }}
+          validate!(result, purpose)
+          result
+        end
+
+        # The caller writes the bounded JSON descriptor first, then these raw
+        # bytes. Both directions share the Server's original monotonic deadline.
+        def send(socket, parts:, descriptor:, purpose:, deadline:)
+          expected = self.descriptor(parts, purpose: purpose)
+          reject!("Export descriptor differs from bytes") unless expected == descriptor
+          deadline = [deadline, Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30].min
+          parts.each do |part|
+            offset = 0
+            while offset < part.bytesize
+              wait(socket, deadline, write: true)
+              written = socket.write_nonblock(part.byteslice(offset, [65_536, part.bytesize - offset].min), exception: false)
+              offset += written unless written == :wait_writable
+            end
+          end
+        end
+
+        def validate!(descriptor, purpose)
+          total, count, each = LIMITS.fetch(purpose) { reject!("Unknown source transfer purpose") }
+          unless descriptor.is_a?(Hash) && descriptor.keys.sort == %w[bytes parts sha256 version] &&
+              descriptor["version"] == 1 && descriptor["bytes"].is_a?(Integer) &&
+              descriptor["bytes"].between?(0, total) && descriptor["sha256"].is_a?(String) && descriptor["sha256"].match?(SHA256) &&
+              descriptor["parts"].is_a?(Array) && descriptor["parts"].length.between?(1, count) &&
+              descriptor["parts"].all? { |part| part.is_a?(Hash) && part.keys.sort == %w[bytes sha256] &&
+                part["bytes"].is_a?(Integer) && part["bytes"].between?(0, each) &&
+                part["sha256"].is_a?(String) && part["sha256"].match?(SHA256) } &&
+              descriptor["bytes"] == descriptor["parts"].sum { |part| part["bytes"] } &&
+              (!%i[candidate service_input].include?(purpose) || descriptor["bytes"].positive?)
+            reject!("Invalid or oversized transfer descriptor")
+          end
+          if purpose == :inbox_proof &&
+              (descriptor.fetch("parts").length != 2 || descriptor.fetch("parts").any? { |part| part.fetch("bytes").zero? })
+            reject!("Inbox proof requires exactly two nonempty bounded parts")
+          end
+          if purpose == :receipt_artifacts
+            receipt, *evidence = descriptor.fetch("parts")
+            unless receipt.fetch("bytes").between?(1, 16 * 1024) && evidence.sum { |part| part.fetch("bytes") } <= 256 * 1024
+              reject!("Receipt or evidence exceeds its fixed transfer limit")
+            end
+          end
+          true
+        end
+
+        private
+
+        def read(socket, count, deadline)
+          loop do
+            wait(socket, deadline)
+            bytes = socket.read_nonblock(count, exception: false)
+            return bytes unless bytes == :wait_readable
+          end
+        end
+
+        def wait(socket, deadline, write: false)
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Timeout::Error, "Transfer deadline exceeded" unless remaining.positive?
+          ready = IO.select(write ? nil : [socket], write ? [socket] : nil, nil, remaining)
+          raise Timeout::Error, "Transfer deadline exceeded" unless ready
+        end
+
+        def reject!(message)
+          raise AttemptErrors::MalformedTransfer, message
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/cli/commands/authority/launch.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+require "json"
+require_relative "../../../authority/launch_driver"
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Authority
+          class Launch < Ace::Support::Cli::Command
+            desc "Launch one mapped native worker through the protected gate"
+            option :mapping, required: true, desc: "Installed launch mapping ID"
+            option :assignment, desc: "Managed assignment ID"
+            option :definition, desc: "Current managed assignment definition JSON file"
+            option :step, desc: "Assignment subtree scope"
+            option :base_head, desc: "Exact base commit SHA"
+            option :mutation, desc: "Stable invocation ID for safe replay"
+            option :dry_run, type: :boolean, default: false, desc: "Verify installed boundary without mutation or creation"
+            def call(**options)
+              driver = build_driver(options.fetch(:mapping))
+              result = if options[:dry_run]
+                driver.preflight
+              else
+                %i[assignment definition step base_head].each do |key|
+                  raise ArgumentError, "Missing --#{key.to_s.tr('_', '-')}" unless options[key].is_a?(String) && !options[key].empty?
+                end
+                raise ArgumentError, "assignment definition is oversized" if File.size(options[:definition]) > 32_768
+                args = {assignment_id: options[:assignment], definition_bytes: File.read(options[:definition]),
+                  scope: options[:step], base_head: options[:base_head]}
+                args[:mutation_id] = options[:mutation] if options[:mutation]
+                driver.launch(**args)
+              end
+              puts JSON.generate(result)
+            rescue ArgumentError, SystemCallError, Ace::Runtime::Error, Ace::Assign::Error => error
+              raise Ace::Support::Cli::Error, error.message
+            end
+            private
+            def build_driver(mapping)
+              Ace::Assign::Authority::LaunchDriver.new(mapping_id: mapping)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/cli/commands/authority/serve.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require_relative "../../../authority/server"
+require_relative "../../../authority/router"
+require_relative "../../../authority/launch_lifecycle"
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Authority
+          class Serve < Ace::Support::Cli::Command
+            desc "Serve the installed protected assignment authority"
+            option :authority, required: true, desc: "Installed authority ID"
+            def call(**options)
+              deployment = Ace::Assign::Authority::Deployment.load
+              launch = Ace::Assign::Authority::LaunchLifecycle.new(deployment: deployment)
+              router = Ace::Assign::Authority::Router.new(launch: launch)
+              server = Ace::Assign::Authority::Server.new(authority_id: options.fetch(:authority), deployment: deployment, lifecycle: router)
+              signals = %w[INT TERM].to_h { |signal| [signal, Signal.trap(signal) { server.request_stop }] }
+              server.serve
+            rescue ArgumentError, Ace::Runtime::Error, Ace::Assign::Error => error
+              raise Ace::Support::Cli::Error, error.message
+            ensure
+              signals&.each { |signal, handler| Signal.trap(signal, handler) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/cli/commands/authority/status.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+require "json"
+require_relative "../../../authority/client"
+module Ace
+  module Assign
+    module CLI
+      module Commands
+        module Authority
+          class Status < Ace::Support::Cli::Command
+            desc "Inspect canonical protected launch ownership"
+            option :mapping, required: true, desc: "Installed launch mapping ID"
+            option :assignment, required: true, desc: "Assignment ID"
+            option :attempt, required: true, desc: "Attempt ID"
+            def call(**options)
+              reply = Ace::Assign::Authority::Client.new(mapping_id: options.fetch(:mapping)).call("attempt_status",
+                {"assignment_id" => options.fetch(:assignment), "attempt_id" => options.fetch(:attempt)})
+              puts JSON.generate(reply.data)
+            rescue ArgumentError, Ace::Runtime::Error, Ace::Assign::Error => error
+              raise Ace::Support::Cli::Error, error.message
+            end
+          end
+        end
+      end
+    end
+  end
+end