ace-lab 0.8.0 → 0.13.0

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

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "etc"
+
+module Ace
+  module Lab
+    module Molecules
+      # Verifies role bindings from the trusted install manifest: the role's
+      # account must exist after the account phase, and its instruction
+      # source must be either a supported protocol reference (syntactic
+      # validation only — context resolution belongs to ace-coworker /
+      # ace-nav, see L3.1) or an absolute file path that exists and whose
+      # static permission bits allow the account to read it. ACLs are out
+      # of scope.
+      class RoleVerifier
+        PROTOCOL_PREFIXES = %w[wfi:// prompt:// tmpl://].freeze
+
+        attr_reader :account_lookup, :group_source, :dry_run
+
+        def initialize(account_lookup: nil, group_source: nil, dry_run: false)
+          @account_lookup = account_lookup || method(:lookup_passwd)
+          # Injectable group-membership seam: a callable returning the
+          # gids the named account holds beyond its primary gid
+          # (Etc.group scan in production). Supplementary groups are
+          # ordinary static permission bits — distinct from the ACLs
+          # that are out of scope.
+          @group_source = group_source || method(:supplementary_gids)
+          @dry_run = dry_run
+        end
+
+        # @param role [Hash] normalized manifest role entry
+        # @return [Hash] {id:, account:, instructions:, status:, message:}
+        def call(role:)
+          base = {"id" => role["id"], "account" => role["account"],
+                  "instructions" => role["instructions"]}
+
+          entry = account_lookup.call(role["account"])
+          if entry.nil? && !dry_run
+            return base.merge("status" => "failed",
+              "message" => "role '#{role['id']}' account '#{role['account']}' is not available; " \
+                "fix the account phase first")
+          end
+
+          instructions = role["instructions"]
+          return base.merge("status" => "verified", "message" => nil) if protocol?(instructions)
+
+          verify_file(base, instructions, entry)
+        end
+
+        # Readiness probe for a project/worktree directory used by a
+        # target executor (task 8xg.t.sbz.7.4, LAB-2): every ancestor of
+        # the RESOLVED path must grant the account search (x) permission
+        # and the directory itself must grant read+write+search (the
+        # executor clones and provisions worktrees inside it — a
+        # directory without x on itself is unusable however rw it is).
+        # Returns nil when the account can work in the directory, or a
+        # concrete reason. Same governing-class permission logic as the
+        # instruction checks so the two can never drift apart.
+        def directory_access_reason(path, entry)
+          resolved = File.realpath(path)
+          current = File.dirname(resolved)
+          loop do
+            stat = File.stat(current)
+            return search_denied(current, entry) if (permission_bits(stat, entry) & 0o1).zero?
+            break if current == "/"
+
+            current = File.dirname(current)
+          end
+          stat = File.stat(resolved)
+          return work_denied(resolved, entry) if (permission_bits(stat, entry) & 0o7) != 0o7
+
+          nil
+        rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+          "'#{path}' does not exist or cannot be inspected for account '#{entry.name}'"
+        end
+
+        # Readiness probe for an executable the target executor must be
+        # able to RUN (PR #393 final audit, FINAL-LAB3): every ancestor
+        # of the RESOLVED path must grant search (x) and the file itself
+        # must be a regular file granting the account execute through
+        # its governing permission class — an installer-owned 0700
+        # executable is NOT available to a different-uid executor.
+        # Returns nil when the account can execute it, or a concrete
+        # reason (same governing-class logic as the other probes).
+        def executable_access_reason(path, entry)
+          resolved = File.realpath(path)
+          current = File.dirname(resolved)
+          loop do
+            stat = File.stat(current)
+            return search_denied(current, entry) if (permission_bits(stat, entry) & 0o1).zero?
+            break if current == "/"
+
+            current = File.dirname(current)
+          end
+          stat = File.stat(resolved)
+          return "'#{resolved}' is not a regular file" unless stat.file?
+          return execute_denied(resolved, entry) if (permission_bits(stat, entry) & 0o1).zero?
+
+          nil
+        rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+          "'#{path}' does not exist or cannot be inspected for account '#{entry.name}'"
+        end
+
+        private
+
+        def search_denied(directory, entry)
+          "'#{directory}' denies search permission to account '#{entry.name}'; the target " \
+            "executor cannot reach the project through this ancestor"
+        end
+
+        def work_denied(directory, entry)
+          "'#{directory}' denies read/write/search permission to account '#{entry.name}'; the " \
+            "target executor cannot work inside the project"
+        end
+
+        def execute_denied(file, entry)
+          "'#{file}' denies execute permission to account '#{entry.name}'; the target " \
+            "executor cannot run it"
+        end
+
+        def protocol?(instructions)
+          PROTOCOL_PREFIXES.any? { |prefix| instructions.start_with?(prefix) }
+        end
+
+        # entry is nil only in dry-run for an account the account phase
+        # would create: readability depends on a uid that does not exist
+        # yet, so the binding is predicted verified once the file itself
+        # checks out.
+        def verify_file(base, path, entry)
+          stat = File.stat(path)
+          unless stat.file?
+            return base.merge("status" => "failed",
+              "message" => "instructions '#{path}' is not a regular file")
+          end
+
+          if entry && !readable_by_account?(stat, entry)
+            return base.merge("status" => "failed",
+              "message" => "instructions '#{path}' is not readable by account '#{entry.name}' " \
+                "(static permission bits; ACLs are out of scope)")
+          end
+
+          # Read bits on the file alone are not enough: POSIX requires
+          # the search (x) bit on EVERY ancestor directory of the
+          # resolved path, or the account cannot reach the file at all
+          # (a 0644 file behind a 0700 directory is unreachable).
+          if entry && !reachable_by_account?(path, entry)
+            return base.merge("status" => "failed",
+              "message" => "instructions '#{path}' is not reachable by account '#{entry.name}' " \
+                "(an ancestor directory denies search permission; static permission bits; " \
+                "ACLs are out of scope)")
+          end
+
+          base.merge("status" => "verified", "message" => nil)
+        rescue Errno::ENOENT
+          base.merge("status" => "failed",
+            "message" => "instructions file '#{path}' does not exist")
+        rescue SystemCallError => e
+          base.merge("status" => "failed",
+            "message" => "instructions file '#{path}' could not be verified (#{e.class.name})")
+        end
+
+        # Reachability: every ancestor of the RESOLVED path must grant
+        # the account search permission through its governing class.
+        # The final component is resolved too (File.realpath(path)):
+        # realpath follows both ancestor symlinks AND a symlink at the
+        # instruction file itself, mirroring what open(2) traverses —
+        # judging only the symlink's own ancestors would miss an
+        # unsearchable directory on the target's path. An unresolvable
+        # or unstattable ancestor is conservatively unreachable.
+        def reachable_by_account?(path, entry)
+          current = File.dirname(File.realpath(path))
+          loop do
+            stat = File.stat(current)
+            return false if (permission_bits(stat, entry) & 0o1).zero?
+            break if current == "/"
+
+            current = File.dirname(current)
+          end
+          true
+        rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+          false
+        end
+
+        # POSIX access checks do not fall through permission classes: a
+        # file owned by the account is governed by the owner bits alone —
+        # group/other bits never apply. Short-circuit per class so an
+        # owner-permission-bit-clear file can never verify through a
+        # gid match. The group class matches ANY group the account is a
+        # member of — primary gid or supplementary (round 5): the
+        # runtime's group credentials include them, so a
+        # supplementary-group-granted permission genuinely applies.
+        # Returns the governing class's rwx bits normalized to the low
+        # octal (r=4, w=2, x=1), shared by the file-read check and the
+        # ancestor search check so the two can never drift apart.
+        def permission_bits(stat, entry)
+          return (stat.mode >> 6) & 0o7 if stat.uid == entry.uid
+          if stat.gid == entry.gid || group_source.call(entry.name).include?(stat.gid)
+            return (stat.mode >> 3) & 0o7
+          end
+
+          stat.mode & 0o7
+        end
+
+        def readable_by_account?(stat, entry)
+          (permission_bits(stat, entry) & 0o4).nonzero?
+        end
+
+        def supplementary_gids(username)
+          gids = []
+          Etc.group { |group| gids << group.gid if group.mem.include?(username) }
+          gids
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/organisms/install.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../molecules/install_manifest_loader"
+require_relative "../molecules/grant_provisioner"
+require_relative "prepare"
+require_relative "project_add"
+require_relative "verify"
+
+module Ace
+  module Lab
+    module Organisms
+      # Orchestrates the full new-lab installation (L8.3, task
+      # 8xg.t.sbz.7.2) from the trusted install manifest by composing
+      # the existing molecules in a fixed order — nothing here
+      # duplicates them:
+      #
+      #   1. foreign-lab guard (BEFORE any mutation): the trusted
+      #      authorization document must not grant projects this
+      #      manifest does not declare — a ready/foreign lab is refused
+      #      with a classified error and zero writes;
+      #   2. `Prepare` (L8.1): accounts → directories → keys → roles;
+      #   3. `ProjectAdd` (L8.2) per declared project: repository,
+      #      private `_overseer`, project registry, runtime HITL route
+      #      configuration (the manifest's `kind: hitl` adapters
+      #      projected into `.ace/hitl/config.yml`, FINAL-LAB2) and
+      #      executor ownership propagation — each project is isolated;
+      #      one failing project does not block the others;
+      #   4. `GrantProvisioner`: trusted-tier principal grants that
+      #      make the installed projects visible to `ace-lab projects`
+      #      and `ace-overseer projects`;
+      #   5. `Verify` (final stage, task 8xg.t.sbz.7.4): the declared
+      #      adapters and required tools are part of the SAME trusted
+      #      manifest (validated at load, reported under `adapters` /
+      #      `tools`), and the converged lab must prove ready UNDER THE
+      #      TARGET ACCOUNTS — tool availability, adapter commands and
+      #      every other readiness check — or install reports not ok.
+      #      Dry runs skip this stage (nothing has converged to verify).
+      #
+      # Every step is idempotent, so an interrupted re-run converges
+      # where steps already completed (the resume contract .7.3 builds
+      # on: no journal — the report is a per-step record in prepare's
+      # established shape). The organism owns no new state: it writes
+      # only through the provisioners above; the trusted manifest
+      # remains the single owner of the adapter/tool declarations.
+      class Install
+        attr_reader :manifest_path, :dry_run, :platform
+
+        def initialize(manifest_path: nil, runner: nil, account_lookup: nil, privileged: nil,
+          platform: nil, dry_run: false, prepare: nil, project_add: nil, grants: nil, verify: nil)
+          @manifest_path = manifest_path || Ace::Lab.install_manifest_path
+          @runner = runner
+          @account_lookup = account_lookup
+          @privileged = privileged
+          @platform = platform
+          @dry_run = dry_run
+          @prepare = prepare
+          @project_add = project_add
+          @grants = grants
+          @verify = verify
+        end
+
+        # @param dry_run [Boolean, nil] per-call override of the
+        #   constructor default (the CLI passes its --dry-run here)
+        # @return [Hash] aggregated report (ok / dry_run / machine /
+        #   manifest / prepare / projects / grants / adapters / tools /
+        #   verify)
+        # @raise [Ace::Lab::InvalidConfigurationError] missing, untrusted
+        #   or invalid manifest, or a foreign lab refusing overwrite
+        #   before any mutation
+        def call(dry_run: nil)
+          effective_dry_run = dry_run.nil? ? self.dry_run : dry_run
+          manifest = Molecules::InstallManifestLoader.load(path: manifest_path, platform: platform)
+          declared_projects = manifest["projects"].map { |project| project["id"] }
+
+          conflict = grants_molecule.foreign_grants?(declared_projects)
+          if conflict
+            raise Ace::Lab::InvalidConfigurationError,
+              "refusing to install over a foreign lab: #{conflict}"
+          end
+
+          prepare_report = prepare_organism.call(dry_run: effective_dry_run)
+          prepare_ok = prepare_report["ok"]
+
+          projects = manifest["projects"].map do |project|
+            if prepare_ok
+              project_add_organism.call(
+                id: project["id"], path: project["path"],
+                remote: project["remote"], label: project["label"],
+                owner: project_owner(manifest, project["path"]),
+                hitl_adapters: manifest["adapters"],
+                dry_run: effective_dry_run
+              )
+            else
+              dependency_failed_project(project,
+                "prepare did not converge; fix the prepare phase first", effective_dry_run)
+            end
+          end
+          projects_ok = projects.all? { |report| report["ok"] }
+
+          grants = if prepare_ok && projects_ok
+            grants_molecule.call(
+              desired: manifest["grants"], declared_projects: declared_projects,
+              dry_run: effective_dry_run
+            )
+          else
+            {"path" => Ace::Lab.authorization_path, "status" => "failed", "principals" => {},
+              "kept" => [], "dry_run" => effective_dry_run,
+              "message" => "install steps did not converge; fix the failing steps first " \
+                "(trusted grants are configured only for a converged install)"}
+          end
+
+          verify_report = verify_stage(manifest, effective_dry_run)
+
+          {
+            "ok" => prepare_ok && projects_ok && grants["status"] != "failed" &&
+              verify_stage_ok?(verify_report),
+            "dry_run" => effective_dry_run,
+            "machine" => manifest["machine"],
+            "manifest" => manifest_path,
+            "prepare" => prepare_report,
+            "projects" => projects,
+            "grants" => grants,
+            "adapters" => manifest["adapters"],
+            "tools" => manifest["tools"],
+            "verify" => verify_report
+          }
+        end
+
+        private
+
+        # Final install verification (LAB-3): read-only, over the
+        # converged artifacts. A wet run's readiness gates `ok`; a dry
+        # run has nothing converged to verify and reports the stage
+        # skipped instead of a guaranteed failure.
+        def verify_stage(manifest, dry_run)
+          return {"ready" => nil, "status" => "skipped",
+                  "message" => "verification runs on the converged lab; dry-run predicts the " \
+                    "steps above only"} if dry_run
+
+          verify_organism.call
+        rescue Ace::Lab::InvalidConfigurationError => e
+          {"ready" => false, "status" => "failed",
+           "message" => "final verification could not run: #{e.message}"}
+        rescue StandardError => e
+          {"ready" => false, "status" => "failed",
+           "message" => "final verification crashed: #{e.class}: #{e.message}"}
+        end
+
+        def verify_stage_ok?(report)
+          report["ready"] != false
+        end
+
+        def verify_organism
+          @verify || Verify.new(
+            manifest_path: manifest_path, runner: @runner, account_lookup: @account_lookup,
+            authorization_path: grants_molecule.authorization_path, platform: platform
+          )
+        end
+
+        # The project's target executor account: the owner of the
+        # declared directory the project lives in (longest prefix
+        # match; a directory declared AS the exact project path matches
+        # its own project too); projects outside any declared directory
+        # are left ownership-neutral.
+        def project_owner(manifest, path)
+          candidates = manifest["directories"].filter_map do |directory|
+            owner = directory["owner"]
+            prefix = directory["path"].to_s
+            matches = path.start_with?("#{prefix}/") || path == prefix
+            owner && matches ? [prefix.length, owner] : nil
+          end
+          candidates.max_by(&:first)&.last
+        end
+
+        def prepare_organism
+          @prepare || Prepare.new(
+            manifest_path: manifest_path, runner: @runner, account_lookup: @account_lookup,
+            privileged: @privileged, platform: platform
+          )
+        end
+
+        def project_add_organism
+          @project_add || ProjectAdd.new(runner: @runner, account_lookup: @account_lookup)
+        end
+
+        def grants_molecule
+          @grants || Molecules::GrantProvisioner.new
+        end
+
+        # Same shape as a ProjectAdd report, with every step failed as a
+        # dependency failure — mirroring prepare's dependency pattern.
+        # `dry_run` is the effective per-call value, not the constructor
+        # default (review r1).
+        def dependency_failed_project(project, message, dry_run)
+          failed = ->(location) { {"location" => location, "status" => "failed", "message" => message} }
+          {
+            "ok" => false,
+            "dry_run" => dry_run,
+            "project" => project["id"],
+            "path" => project["path"],
+            "remote" => project["remote"],
+            "repository" => failed.call(project["path"]),
+            "overseer" => failed.call(File.join(project["path"], ".ace-tasks", "_overseer")),
+            "registry" => failed.call(File.join(project["path"], ".ace", "lab", "config.yml")),
+            "hitl" => failed.call(File.join(project["path"], ".ace", "hitl", "config.yml")),
+            "owner" => failed.call(project["path"])
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/organisms/prepare.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../molecules/install_manifest_loader"
+require_relative "../molecules/account_provisioner"
+require_relative "../molecules/directory_provisioner"
+require_relative "../molecules/key_provisioner"
+require_relative "../molecules/role_verifier"
+
+module Ace
+  module Lab
+    module Organisms
+      # Orchestrates the preparation phase (L8.1) from the trusted install
+      # manifest: accounts → directories → keys → roles, in that fixed
+      # order, each through its idempotent provisioner molecule. The
+      # aggregated report is the contract consumed by `ace-lab project add`
+      # (7.1) and `ace-lab install` (7.2); `ok` means zero failed items.
+      # Key and role items whose account failed are reported as dependency
+      # failures instead of being attempted. No state is written beyond
+      # what the manifest declares — this organism owns no journal.
+      class Prepare
+        attr_reader :manifest_path, :dry_run, :platform
+
+        def initialize(manifest_path: nil, runner: nil, account_lookup: nil, privileged: nil,
+          platform: nil, dry_run: false)
+          @manifest_path = manifest_path || Ace::Lab.install_manifest_path
+          @runner = runner
+          @account_lookup = account_lookup
+          @privileged = privileged
+          @platform = platform
+          @dry_run = dry_run
+        end
+
+        # @param dry_run [Boolean, nil] per-call override of the
+        #   constructor default (the CLI passes its --dry-run here)
+        # @return [Hash] aggregated report (ok / dry_run / machine /
+        #   manifest / accounts / directories / keys / roles)
+        # @raise [Ace::Lab::InvalidConfigurationError] missing, untrusted,
+        #   unparseable or schema-invalid manifest
+        def call(dry_run: nil)
+          effective_dry_run = dry_run.nil? ? self.dry_run : dry_run
+          manifest = Molecules::InstallManifestLoader.load(path: manifest_path, platform: platform)
+          accounts = prepare_accounts(manifest["accounts"], effective_dry_run)
+          available = available_accounts(accounts)
+          unresolved = unresolved_accounts(accounts)
+          directories = prepare_directories(manifest["directories"], effective_dry_run, available,
+            unresolved)
+          keys = prepare_keys(manifest["keys"], manifest["machine"], manifest["accounts"], available,
+            unresolved, effective_dry_run)
+          roles = prepare_roles(manifest["roles"], available, unresolved, effective_dry_run)
+
+          {
+            "ok" => [accounts, directories, keys, roles].flatten.none? { |item| item["status"] == "failed" },
+            "dry_run" => effective_dry_run,
+            "machine" => manifest["machine"],
+            "manifest" => manifest_path,
+            "accounts" => accounts,
+            "directories" => directories,
+            "keys" => keys,
+            "roles" => roles
+          }
+        end
+
+        private
+
+        def prepare_accounts(entries, dry_run)
+          provisioner = Molecules::AccountProvisioner.new(
+            runner: @runner, account_lookup: @account_lookup, privileged: @privileged,
+            platform: @platform, dry_run: dry_run
+          )
+          entries.map { |account| provisioner.call(account: account) }
+        end
+
+        def prepare_directories(entries, dry_run, available, unresolved)
+          provisioner = Molecules::DirectoryProvisioner.new(
+            account_lookup: @account_lookup, dry_run: dry_run, available_accounts: available
+          )
+          entries.map do |directory|
+            if unresolved.include?(directory["owner"])
+              # linux uid-lag edge, mirroring prepare_keys (round 5):
+              # the account phase created the owner but its uid is not
+              # yet resolvable — the remedy is a convergence rerun,
+              # not "fix the account phase" (that phase did not fail).
+              {"path" => directory["path"], "owner" => directory["owner"],
+               "mode" => directory["mode"], "status" => "failed",
+               "message" => "owner account '#{directory["owner"]}' was created but its uid is " \
+                 "not yet resolvable; rerun ace-lab prepare"}
+            else
+              provisioner.call(directory: directory)
+            end
+          end
+        end
+
+        def prepare_keys(entries, machine, manifest_accounts, available, unresolved, dry_run)
+          provisioner = Molecules::KeyProvisioner.new(
+            runner: @runner, account_lookup: @account_lookup, dry_run: dry_run
+          )
+          by_username = manifest_accounts.to_h { |account| [account["username"], account] }
+          entries.map do |key|
+            account = by_username.fetch(key["account"])
+            username = account["username"]
+            if unresolved.include?(username)
+              # linux uid-lag edge: the account phase reported created
+              # with a nil uid (post-useradd passwd lookup lag) — the
+              # remedy is a convergence rerun, not "fix the account
+              # phase" (that phase did not fail).
+              {"account" => username, "path" => key["path"], "status" => "failed",
+               "fingerprint" => nil,
+               "message" => "account '#{username}' was created but its uid is not yet " \
+                 "resolvable; rerun ace-lab prepare"}
+            elsif available.include?(username)
+              provisioner.call(key: key, account: account, machine: machine)
+            else
+              {"account" => username, "path" => key["path"], "status" => "failed",
+               "fingerprint" => nil,
+               "message" => "account '#{username}' is not available; fix the account phase first"}
+            end
+          end
+        end
+
+        def prepare_roles(entries, available, unresolved, dry_run)
+          provisioner = Molecules::RoleVerifier.new(account_lookup: @account_lookup, dry_run: dry_run)
+          entries.map do |role|
+            if unresolved.include?(role["account"])
+              # linux uid-lag edge, mirroring prepare_keys (round 5):
+              # same rerun remedy, not "fix the account phase".
+              {"id" => role["id"], "account" => role["account"], "instructions" => role["instructions"],
+               "status" => "failed",
+               "message" => "account '#{role["account"]}' was created but its uid is not yet " \
+                 "resolvable; rerun ace-lab prepare"}
+            elsif available.include?(role["account"])
+              provisioner.call(role: role)
+            else
+              {"id" => role["id"], "account" => role["account"], "instructions" => role["instructions"],
+               "status" => "failed",
+               "message" => "account '#{role['account']}' is not available; fix the account phase first"}
+            end
+          end
+        end
+
+        def available_accounts(account_reports)
+          account_reports.reject { |report| report["status"] == "failed" }
+            .map { |report| report["username"] }
+        end
+
+        # Accounts whose creation succeeded but whose uid is not yet
+        # resolvable (linux post-useradd passwd lag): the phase did not
+        # fail, but dependent key provisioning cannot chown to them.
+        def unresolved_accounts(account_reports)
+          account_reports.select { |report| report["status"] == "created" && report["uid"].nil? }
+            .map { |report| report["username"] }
+        end
+      end
+    end
+  end
+end