ace-lab 0.8.0 → 0.13.0

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Classifies the lab configuration namespace into exactly three
+      # distinguished states (task 8xg.t.sbz.6.0): a valid empty set, missing
+      # configuration, and a source error are never conflated.
+      #
+      #   :defaults_only — no overlay exists (gem defaults only) ⇒ missing
+      #                    configuration; informational, exit-eligible success
+      #   :configured    — at least one overlay present and valid; carries
+      #                    topology counts (0/0/0 is a valid empty set)
+      #   :invalid       — any cascade document unparsable/non-mapping or a
+      #                    schema violation; carries the path-bearing message
+      #
+      # Also echoes runtime *configuration files* (project, user, ACE_RUNTIME
+      # env): presence + the configured runtime value. No runtime detection
+      # and no ace-runtime dependency — live runtime availability is
+      # ace-herdr status's dimension.
+      class ConfigStateClassifier
+        RUNTIME_PATTERNS = %w[runtime/config.yml runtime/config.yaml].freeze
+
+        class << self
+          # @param documents [Array<Hash>, nil] cascade_documents output;
+          #   nil means the cascade itself raised before documents existed
+          # @param cascade_error [String, nil] path-bearing message from the
+          #   InvalidConfigurationError raised while reading the cascade
+          # @param root [String] project root for runtime config reads
+          # @return [Hash] classified configuration section
+          def classify(documents:, cascade_error: nil, root: Dir.pwd)
+            return invalid_config(cascade_error) if cascade_error
+
+            documents ||= []
+            # No cascade documents at all (not even gem defaults): nothing
+            # is broken, the lab is simply unconfigured.
+            return missing_config if documents.empty?
+
+            overlays = documents.reject { |document| document[:defaults] }
+            user_overlay_dir = File.join(Dir.home, ".ace")
+            project = overlays.find { |document| !document[:path].start_with?(user_overlay_dir) }
+            user = overlays.find { |document| document[:path].start_with?(user_overlay_dir) }
+
+            merged = deep_merge_documents(documents)
+            begin
+              topology = Atoms::TopologySchema.normalize!(merged).fetch("topology", {})
+              {
+                state: overlays.empty? ? :defaults_only : :configured,
+                overlays: {project: project&.dig(:path), user: user&.dig(:path)},
+                source_path: overlays.first&.dig(:path),
+                error: nil,
+                topology: {
+                  projects: topology.fetch("projects", []).length,
+                  agents: topology.fetch("agents", []).length,
+                  services: topology.fetch("services", []).length
+                }
+              }
+            rescue Ace::Lab::InvalidConfigurationError => e
+              invalid_config(e.message)
+            end
+          end
+
+          # Runtime configuration echo: files first (project, then user),
+          # then the ACE_RUNTIME environment variable. Presence and value
+          # only — never liveness.
+          #
+          # @param root [String] project root
+          # @return [Hash] runtime configuration section
+          def runtime_config(root: Dir.pwd)
+            candidates = [
+              {source: "project", paths: RUNTIME_PATTERNS.map { |pattern| File.join(root, ".ace", pattern) }},
+              {source: "user", paths: RUNTIME_PATTERNS.map { |pattern| File.join(Dir.home, ".ace", pattern) }}
+            ]
+            found = candidates.find do |candidate|
+              candidate[:paths].any? { |candidate_path| File.exist?(candidate_path) }
+            end
+            if found
+              path = found[:paths].find { |candidate_path| File.exist?(candidate_path) }
+              document = begin
+                require "yaml"
+                YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+              rescue StandardError
+                nil
+              end
+              if document.is_a?(Hash)
+                return {state: :valid, source: found[:source], path: path, runtime: document["runtime"]}
+              end
+
+              return {state: :invalid, source: found[:source], path: path, runtime: nil,
+                      error: "#{path} could not be parsed as a YAML mapping"}
+            end
+            return runtime_from_env if ENV["ACE_RUNTIME"] && !ENV["ACE_RUNTIME"].empty?
+
+            {state: :absent, source: nil, path: nil, runtime: nil}
+          end
+
+          private
+
+          def runtime_from_env
+            {state: :valid, source: "env", path: nil, runtime: ENV["ACE_RUNTIME"]}
+          end
+
+          def invalid_config(message)
+            {
+              state: :invalid,
+              overlays: {},
+              source_path: nil,
+              error: message,
+              topology: {projects: 0, agents: 0, services: 0}
+            }
+          end
+
+          def missing_config
+            {
+              state: :defaults_only,
+              overlays: {},
+              source_path: nil,
+              error: nil,
+              topology: {projects: 0, agents: 0, services: 0}
+            }
+          end
+
+          # Cascade merge mirroring the canonical ADR-22 resolver:
+          # cascade_documents lists documents highest-priority-first, so
+          # reduce in reverse (defaults first, nearest overlay last — later
+          # wins). Arrays replace (they are topology inventories, not
+          # additive sets).
+          def deep_merge_documents(documents)
+            documents.reverse.reduce({}) { |merged, document| deep_merge(merged, document[:document]) }
+          end
+
+          def deep_merge(base, overlay)
+            base.merge(overlay) do |_key, base_value, overlay_value|
+              if base_value.is_a?(Hash) && overlay_value.is_a?(Hash)
+                deep_merge(base_value, overlay_value)
+              else
+                overlay_value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "etc"
+require "fileutils"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently ensures a manifest-declared directory exists with the
+      # declared mode and ownership. Pre-existing directories are never
+      # silently taken over: a symlink at the path, a non-directory, or a
+      # directory owned by a different account than declared is refused
+      # with a resolve-manually message; only mode drift on an
+      # owner-matching directory is repaired. Permission failures
+      # (EPERM/EACCES) classify as actionable missing-permission reports.
+      class DirectoryProvisioner
+        attr_reader :account_lookup, :dry_run
+
+        # available_accounts [Enumerable<String>, nil] usernames the
+        # account phase will have (exists/created/would_create) — the
+        # orchestrator's already-computed set, threaded in so dry-run
+        # can predict the wet run's owner_unavailable failure for a
+        # directory whose owner account failed permanently (mirroring
+        # keys/roles dependency prediction). nil = predict from live
+        # passwd only (standalone use).
+        def initialize(account_lookup: nil, dry_run: false, available_accounts: nil)
+          @account_lookup = account_lookup || method(:lookup_passwd)
+          @dry_run = dry_run
+          @available_accounts = available_accounts
+        end
+
+        # @param directory [Hash] normalized manifest directory entry
+        # @return [Hash] {path:, owner:, mode:, status:, message:}
+        def call(directory:)
+          path = directory["path"]
+          mode = directory["mode"].to_i(8)
+          stat = begin
+            File.lstat(path)
+          rescue Errno::ENOENT
+            nil
+          end
+
+          if stat.nil?
+            create_missing(path, directory, mode)
+          elsif stat.symlink?
+            refuse_symlink(path, directory)
+          elsif !stat.directory?
+            failure(path, "path '#{path}' is occupied by a non-directory; refusing", directory)
+          else
+            ensure_existing(path, directory, stat, mode)
+          end
+        rescue Errno::EPERM, Errno::EACCES
+          failure(path,
+            "insufficient permissions while preparing '#{path}'; rerun ace-lab prepare with sudo " \
+            "or adjust ownership manually", directory)
+        rescue SystemCallError => e
+          failure(path, "path '#{path}' could not be prepared (#{e.class.name})", directory)
+        end
+
+        private
+
+        def base(path, directory)
+          {"path" => path, "owner" => directory["owner"], "mode" => directory["mode"]}
+        end
+
+        # Every failed entry carries the full {path, owner, mode} shape —
+        # JSON consumers must see one shape per section, including
+        # rescue-path failures.
+        def failure(path, message, directory)
+          base(path, directory).merge("status" => "failed", "message" => message)
+        end
+
+        def refuse_symlink(path, directory)
+          failure(path, "path '#{path}' is a symbolic link; refusing", directory)
+        end
+
+        # Ownership an existing directory must match: the declared owner
+        # account's uid, or the installer's euid when no owner is declared.
+        # Returns nil when the declared owner account is not resolvable on
+        # this machine (account phase not yet green).
+        def expected_owner_uid(directory)
+          return Process.euid unless directory["owner"]
+
+          entry = account_lookup.call(directory["owner"])
+          entry && entry.uid
+        end
+
+        def create_missing(path, directory, mode)
+          if dry_run
+            # A declared owner whose account phase failed permanently
+            # (not merely would_create) makes the wet run fail with
+            # owner_unavailable — the prediction must say so instead of
+            # would_create.
+            if directory["owner"] && @available_accounts &&
+                !@available_accounts.include?(directory["owner"])
+              return owner_unavailable(path, directory, "fix the account phase first")
+            end
+
+            return base(path, directory).merge("status" => "would_create", "message" => nil)
+          end
+
+          missing = chown_target(directory)
+          return owner_unavailable(path, directory) if directory["owner"] && missing.nil?
+
+          refusal = create_leaf(path, directory)
+          return refusal if refusal
+
+          FileUtils.chmod(mode, path)
+          chown_to_owner(path, directory, missing)
+          base(path, directory).merge("status" => "created", "message" => nil)
+        end
+
+        # Close the create-time TOCTOU window as far as stdlib allows:
+        # intermediate components are created per the documented policy
+        # (mkdir_p follows existing components — the manifest is
+        # root-owned and only the leaf carries declared values), but the
+        # leaf uses Dir.mkdir, whose EEXIST on a planted symlink never
+        # follows it, and the leaf is re-lstat'd before any chmod/chown:
+        # a leaf that is not a real directory this process just created
+        # is refused instead of mutated. The window between this
+        # re-lstat and the chmod/chown that follow is a documented
+        # accepted residual (usage.md).
+        def create_leaf(path, directory)
+          FileUtils.mkdir_p(File.dirname(path))
+          Dir.mkdir(path)
+          post = lstat(path)
+          return nil if post && post.directory? && post.uid == Process.euid
+
+          failure(path, "path '#{path}' changed while preparing; refusing — rerun ace-lab prepare",
+            directory)
+        rescue Errno::EEXIST
+          failure(path, "path '#{path}' appeared or was replaced while preparing; " \
+            "refusing — rerun ace-lab prepare", directory)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          failure(path, "path '#{path}' could not be created; rerun ace-lab prepare", directory)
+        end
+
+        def ensure_existing(path, directory, stat, mode)
+          expected_uid = expected_owner_uid(directory)
+          if directory["owner"] && expected_uid.nil?
+            return owner_unavailable(path, directory)
+          end
+
+          if stat.uid != expected_uid
+            owner = directory["owner"] || "installer"
+            return failure(path,
+              "directory '#{path}' exists but is owned by uid #{stat.uid} " \
+              "(expected account '#{owner}'); refusing takeover — resolve ownership manually " \
+              "or rerun ace-lab prepare with sudo", directory)
+          end
+
+          if (stat.mode & 0o7777) == mode
+            return base(path, directory).merge("status" => "exists", "message" => nil)
+          end
+
+          return base(path, directory).merge("status" => "would_fix_mode", "message" => nil) if dry_run
+
+          # Stale-stat re-check: the owner-matching lstat above may be
+          # outdated by the time chmod runs; re-lstat and refuse unless
+          # the leaf is still a real, owner-matching directory.
+          fresh = lstat(path)
+          unless fresh && fresh.directory? && fresh.uid == expected_uid
+            return failure(path,
+              "directory '#{path}' changed while preparing; refusing — rerun ace-lab prepare", directory)
+          end
+
+          FileUtils.chmod(mode, path)
+          base(path, directory).merge("status" => "mode_fixed", "message" => nil)
+        end
+
+        def lstat(path)
+          File.lstat(path)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          nil
+        end
+
+        def owner_unavailable(path, directory, remedy = nil)
+          remedy ||= if dry_run
+            "the account phase would create it; ownership of existing '#{path}' cannot be " \
+              "predicted before the account exists — rerun prepare --dry-run after the account phase"
+          else
+            "fix the account phase first"
+          end
+          failure(path,
+            "owner account '#{directory["owner"]}' is not available on this machine; " \
+            "#{remedy}", directory)
+        end
+
+        def chown_target(directory)
+          return nil unless directory["owner"]
+
+          account_lookup.call(directory["owner"])
+        end
+
+        def chown_to_owner(path, directory, entry)
+          FileUtils.chown(entry.uid, entry.gid, path) if entry
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "grant_resolver"
+require "yaml"
+require "date"
+require "fileutils"
+
+module Ace
+  module Lab
+    module Molecules
+      # Writes the trusted-tier principal grants (task 8xg.t.sbz.7.2,
+      # L8.3): the `principals` section of the deployment-owned
+      # authorization document at the fixed AUTHORIZATION_PATH — the only
+      # place GrantResolver reads grants from, so `ace-lab projects` /
+      # `ace-overseer projects` see the installed projects with no
+      # read-side change.
+      #
+      # The installer owns this configuration, but never overwrites a
+      # foreign lab: a document whose principals grant projects outside
+      # the manifest's declared set is foreign (`foreign_grants?`, used
+      # by the installer as a before-any-mutation guard), and a manifest
+      # that would REMOVE an existing grant is refused — grants only
+      # grow. All other sections of the document are preserved
+      # untouched. Writes are atomic (temp file + rename) with mode
+      # 0644, mirroring the registry's write discipline.
+      class GrantProvisioner
+        STATUS_DRY = {"created" => "would_create", "updated" => "would_update"}.freeze
+
+        # @param resolver [Object] trusted-read seam (defaults to
+        #   GrantResolver; injected in tests)
+        # @param authorization_path [String] trusted grants location
+        def initialize(resolver: GrantResolver, authorization_path: Ace::Lab.authorization_path)
+          @resolver = resolver
+          @authorization_path = authorization_path
+        end
+
+        # @return [String] the trusted grants location this molecule
+        #   converges — install threads it into the final Verify stage.
+        attr_reader :authorization_path
+
+        # Foreign-lab detection: an existing trusted document that grants
+        # projects outside the manifest's declared set belongs to a
+        # different lab and must never be overwritten by this install.
+        #
+        # @param declared_projects [Array<String>] project ids declared
+        #   by the install manifest
+        # @return [String, nil] conflict message, nil when compatible
+        # @raise [Ace::Lab::InvalidConfigurationError] the trusted
+        #   document exists but fails verification or parsing — a lab
+        #   the installer cannot reason about is treated as foreign
+        def foreign_grants?(declared_projects)
+          document = read_document
+          return nil if document.nil?
+
+          (document["principals"] || {}).each do |principal, policy|
+            foreign = granted_projects(policy) - declared_projects
+            next if foreign.empty?
+
+            return "trusted authorization file #{@authorization_path} already grants " \
+              "project(s) #{foreign.sort.join(', ')} to principal '#{principal}' — this lab's " \
+              "manifest does not declare them; refusing to overwrite a foreign lab"
+          end
+          nil
+        end
+
+        # Idempotently converge the principal grants.
+        #
+        # @param desired [Hash] principal => project ids (normalized
+        #   manifest grants)
+        # @param declared_projects [Array<String>] manifest project ids
+        # @param dry_run [Boolean]
+        # @return [Hash] {path:, status:, principals:, message:} where
+        #   status is created / updated / exists / would_create /
+        #   would_update / failed and principals carries one entry per
+        #   desired principal
+        def call(desired:, declared_projects:, dry_run: false)
+          # Exposed on every report/failure so the grants section of the
+          # install JSON has one uniform schema (the top-level report
+          # also carries it; consumers may read either).
+          @dry_run = dry_run
+          document = begin
+            read_document
+          rescue Ace::Lab::InvalidConfigurationError => e
+            return failure(e.message)
+          end
+          existing = document ? (document["principals"] || {}) : {}
+
+          removal = desired.filter_map do |principal, projects|
+            granted = existing.key?(principal) ? granted_projects(existing[principal]) : []
+            next if (granted - projects).empty?
+
+            "principal '#{principal}' is already granted project(s) " \
+              "#{(granted - projects).sort.join(', ')} which this manifest does not grant; " \
+              "refusing to remove trusted grants — edit #{@authorization_path} manually"
+          end
+          return failure(removal.join("; ")) unless removal.empty?
+
+          merged, statuses = merge_principals(existing, desired)
+
+          # An empty grants manifest over an absent document is a no-op
+          # (review r1): nothing is granted, so no empty authorization
+          # document is created.
+          if document.nil? && merged.empty?
+            return report("skipped", {}, "no grants declared and no trusted document present; " \
+              "nothing to write", existing, desired)
+          end
+
+          aggregate = if statuses.values.include?("created") && existing.empty?
+            "created"
+          elsif statuses.values.any? { |status| %w[created updated].include?(status) }
+            "updated"
+          else
+            "exists"
+          end
+
+          # Dry-run parity: per-principal predictions mirror the wet
+          # statuses (an already-converged principal stays `exists`).
+          statuses = statuses.transform_values { |status| STATUS_DRY.fetch(status, status) } if dry_run
+
+          return report(STATUS_DRY.fetch(aggregate, aggregate), statuses, nil, existing,
+            desired) if dry_run
+
+          # Converged: the merged principals deep-equal the parsed
+          # existing mapping, so the write is skipped — the trusted
+          # document (admin-authored comments included) stays
+          # byte-identical instead of being round-tripped through YAML
+          # (review r1). An absent document is always created.
+          if document && merged == existing
+            return report(aggregate, statuses, nil, existing, desired)
+          end
+
+          write_failure = persist(document, merged)
+          return write_failure if write_failure
+
+          report(aggregate, statuses, nil, existing, desired)
+        rescue Ace::Lab::InvalidConfigurationError => e
+          failure(e.message)
+        end
+
+        private
+
+        # Per-principal convergence: a principal with no grants yet is
+        # `created`, one gaining projects is `updated`, an already
+        # fully-granted one is `exists`. Principals absent from the
+        # manifest are carried over unchanged (never removed).
+        def merge_principals(existing, desired)
+          merged = existing.each_with_object({}) do |(principal, policy), acc|
+            acc[principal] = {"projects" => granted_projects(policy)}
+          end
+          statuses = desired.each_with_object({}) do |(principal, projects), acc|
+            granted = merged.key?(principal) ? merged[principal]["projects"] : []
+            acc[principal] = if granted.empty?
+              "created"
+            elsif (projects - granted).empty?
+              "exists"
+            else
+              "updated"
+            end
+            merged[principal] = {"projects" => (granted | projects).sort}
+          end
+          [merged, statuses]
+        end
+
+        # Atomic write preserving every other section of the document.
+        # Returns nil on success, a failed report otherwise.
+        def persist(document, merged)
+          updated = document ? deep_copy(document) : {}
+          updated["principals"] = merged
+
+          dir = File.dirname(@authorization_path)
+          tmp = File.join(dir, ".authorization.yml.tmp.#{Process.pid}")
+          begin
+            FileUtils.mkdir_p(dir)
+            File.write(tmp, YAML.dump(updated))
+            File.chmod(0o644, tmp)
+            File.rename(tmp, @authorization_path)
+          rescue SystemCallError, IOError => e
+            File.delete(tmp) if File.exist?(tmp)
+            return failure("writing #{@authorization_path} failed: #{e.message}")
+          end
+          nil
+        end
+
+        def report(status, statuses, message, existing, desired)
+          {
+            "path" => @authorization_path,
+            "status" => status,
+            "principals" => statuses,
+            "message" => message,
+            # Always present (empty when nothing is carried over) so
+            # JSON consumers see a stable schema (review r1).
+            "kept" => existing.keys - desired.keys,
+            # Same key set as the gated grants failure in the install
+            # report — one uniform grants-section schema (review L8.4).
+            "dry_run" => @dry_run ? true : false
+          }
+        end
+
+        def failure(message)
+          # `kept` is present (empty) like in every report so JSON
+          # consumers see one stable schema — a failure merges
+          # nothing, so nothing is carried over (resume/verification
+          # readers, tasks 8xg.t.sbz.7.3/.7.4).
+          {"path" => @authorization_path, "status" => "failed", "principals" => {},
+            "message" => message, "kept" => [], "dry_run" => @dry_run ? true : false}
+        end
+
+        # Read and parse the trusted document through the same
+        # fail-closed verification every grant reader uses.
+        # @return [Hash, nil] parsed document, nil when absent
+        # @raise [Ace::Lab::InvalidConfigurationError]
+        def read_document
+          content = @resolver.read_verified(@authorization_path)
+          return nil if content.nil?
+
+          document = begin
+            YAML.safe_load(content, permitted_classes: [Date], aliases: true)
+          rescue Psych::Exception
+            raise Ace::Lab::InvalidConfigurationError,
+              "#{@authorization_path} could not be parsed as YAML; refusing to overwrite"
+          end
+          unless document.is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "#{@authorization_path} must contain a YAML mapping; refusing to overwrite"
+          end
+          principals = document["principals"]
+          return document if principals.nil?
+
+          # Per-principal validation identical to the read side
+          # (GrantResolver.parse_grants): a malformed policy is refused
+          # with the classified error instead of silently rewritten,
+          # and principal names are stripped so a whitespace-padded
+          # existing principal cannot coexist with its stripped twin
+          # after a write (review r1).
+          document.merge("principals" =>
+            GrantResolver.validate_principals(principals, @authorization_path))
+        end
+
+        def granted_projects(policy)
+          policy.is_a?(Hash) && policy["projects"].is_a?(Array) ? policy["projects"] : []
+        end
+
+        def deep_copy(document)
+          YAML.safe_load(YAML.dump(document), permitted_classes: [Date], aliases: true)
+        end
+      end
+    end
+  end
+end