ace-lab 0.13.0 → 0.14.0

data/lib/ace/lab/auth.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "auth/profile_schema"
+require_relative "auth/lease_store"
+require_relative "auth/providers"
+require_relative "auth/credential_handoff"
+require_relative "auth/plugins/env_provider"
+require_relative "auth/plugins/forgejo_provider"
+require_relative "auth/plugins/github_provider"
+require_relative "auth/service"
+
+module Ace
+  module Lab
+    # ace-lab auth (task 8xs.t.pu0.7): short-lived, role-scoped access
+    # for delegated work. The public contract and lease lifecycle live
+    # here; provider protocols live in plugins. Explicit registration
+    # of the bundled plugins — the same precedented pattern as the
+    # ace-git provider registry.
+    module Auth
+      Providers.register("env", Plugins::EnvProvider.new)
+      Providers.register("forgejo", Plugins::ForgejoProvider.new)
+      Providers.register("github", Plugins::GithubProvider.new)
+    end
+  end
+end

data/lib/ace/lab/cli/commands/auth.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        # `ace-lab auth request|status|exec|revoke|reconcile` (task
+        # 8xs.t.pu0.7): the public short-lived-access interface. A
+        # single structured JSON report; refusals and errors are
+        # non-zero with a reason and the escalation addressee; NO
+        # command ever prints a token or exports one to shell history.
+        # status is the read-only readiness view (alongside ace-lab
+        # verify).
+        class Auth < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Short-lived role access: request, status, exec, revoke, reconcile"
+
+          argument :action, required: true, desc: "request | status | exec | revoke | reconcile"
+          argument :target, required: false, desc: "Lease id (status/exec/revoke)"
+
+          option :profile, type: :string, desc: "Auth profile name (request)"
+          option :role, type: :string, desc: "Delegation role (request)"
+          option :task, type: :string, desc: "Task reference (request)"
+          option :assignment, type: :string, desc: "Assignment reference (request)"
+          option :repo, type: :string, repeat: true, desc: "Repository (request, repeatable)"
+          option :ttl, type: :integer, desc: "Requested TTL minutes (request)"
+          option :cmd, type: :string, repeat: true,
+            desc: "Exec command, one argument per repeat, in order (exec)"
+          option :force, type: :boolean, default: false,
+            desc: "Close a revoke-pending lease whose credential is gone (operator-forced terminal; revoke)"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
+
+          def call(action:, target: nil, **options)
+            require_relative "../../auth"
+            service = ::Ace::Lab::Auth::Service.new
+
+            result = case action
+            when "request"
+              require_options!(options, :profile, :role, :task, :assignment)
+              service.request(profile_name: options[:profile], role: options[:role],
+                task: options[:task], assignment: options[:assignment],
+                repos: Array(options[:repo]), ttl_minutes: options[:ttl])
+            when "status"
+              service.status(lease_id: target)
+            when "exec"
+              raise Ace::Support::Cli::Error.new("exec requires a lease id and a command") if target.nil?
+
+              command = Array(options[:cmd])
+              raise Ace::Support::Cli::Error.new("exec requires a command (--cmd, one argument per repeat)") if command.empty?
+
+              service.exec(lease_id: target, argv: command)
+            when "revoke"
+              raise Ace::Support::Cli::Error, "revoke requires a lease id" if target.nil?
+
+              {"lease" => target, "cleanup" => service.revoke(lease_id: target,
+                force: options[:force]).to_s}
+            when "reconcile"
+              {"reconciled" => service.reconcile}
+            else
+              raise Ace::Support::Cli::Error,
+                "unknown auth action '#{action}' (request, status, exec, revoke, reconcile)"
+            end
+
+            render(result)
+            # The child's REAL exit code is the exec exit code — raised
+            # AFTER the single report render, so both outcomes stay
+            # visible without duplicating the report.
+            if action == "exec" && result["exit"] && !result["exit"].zero?
+              raise Ace::Support::Cli::Error.new("exec exited #{result["exit"]}",
+                exit_code: result["exit"])
+            end
+          rescue ::Ace::Lab::Auth::Refusal => e
+            raise Ace::Support::Cli::Error.new("refused: #{e.message}")
+          rescue ::Ace::Lab::Auth::Error => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          private
+
+          def require_options!(options, *keys)
+            missing = keys.reject { |key| options[key] && !options[key].to_s.strip.empty? }
+            unless missing.empty?
+              raise Ace::Support::Cli::Error.new("missing required options: #{missing.map { |k| "--#{k}" }.join(' ')}")
+            end
+          end
+
+          def render(result)
+            # A single structured JSON report: the data is the interface
+            # agents consume (no table form exists for auth reports).
+            puts JSON.pretty_generate(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/prepare.rb

@@ -18,14 +18,16 @@ module Ace
             "accounts" => ->(item) { item["username"] },
             "directories" => ->(item) { item["path"] },
             "keys" => ->(item) { "#{item['account']}:#{item['path']}" },
-            "roles" => ->(item) { item["id"] }
+            "roles" => ->(item) { item["id"] },
+            "gems" => ->(item) { "#{item['name']} #{item['version']}" }
           }.freeze
 
           # "SHA256:" plus the first 20 base64 characters is enough to
           # eyeball-match a key without ballooning the table row.
           FINGERPRINT_WIDTH = 27
 
-          desc "Prepare accounts, directories, permissions, keys and roles from the trusted install manifest"
+          desc "Prepare accounts, directories, permissions, keys, roles and the declared " \
+            "gem set from the trusted install manifest"
 
           example [
             "--dry-run            # Predict all sections without mutating",

data/lib/ace/lab/cli/commands/verify.rb

@@ -16,13 +16,13 @@ module Ace
             "accounts" => "account", "directories" => "directory", "keys" => "account",
             "roles" => "id", "repositories" => "project", "grants" => "principal",
             "registry" => "project", "overseer" => "project",
-            "adapters" => "adapter", "tools" => "tool"
+            "adapters" => "adapter", "tools" => "tool", "gems" => "gem"
           }.freeze
 
           desc "Verify the installed lab's readiness under the target accounts (read-only): " \
             "accounts, directories, key pairs, role instructions, repository origins and " \
             "target-executor access, grant-based project visibility, private _overseer " \
-            "folders, configured communication/HITL adapters, required tools"
+            "folders, configured communication/HITL adapters, required tools, declared gem set"
 
           example [
             "--format json        # Machine-readable report for the overseer / next tool",

data/lib/ace/lab/cli.rb

@@ -13,6 +13,7 @@ require_relative "cli/commands/prepare"
 require_relative "cli/commands/project_add"
 require_relative "cli/commands/install"
 require_relative "cli/commands/verify"
+require_relative "cli/commands/auth"
 
 module Ace
   module Lab
@@ -33,7 +34,8 @@ module Ace
         ["prepare", "Prepare accounts, directories, permissions, keys and roles from the trusted install manifest"],
         ["project add", "Register a project and make it ready for team work (repository, _overseer, lab config)"],
         ["install", "Perform the full new-lab installation from the trusted install manifest"],
-        ["verify", "Verify the installed lab's readiness under the target accounts (read-only)"]
+        ["verify", "Verify the installed lab's readiness under the target accounts (read-only)"],
+        ["auth", "Short-lived role access: request, status, exec, revoke, reconcile"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -67,6 +69,7 @@ module Ace
       register "project add", CLI::Commands::ProjectAdd.new
       register "install", CLI::Commands::Install.new
       register "verify", CLI::Commands::Verify.new
+      register "auth", CLI::Commands::Auth.new
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "fileutils"
+require "pathname"
+
+module Ace
+  module Lab
+    module Molecules
+      # Shared extension-projection primitives (task 8xs.t.pu0.0): the
+      # ONE place that knows how the installed gem's handbook/extensions
+      # tree is located, enumerated, and projected safely — used by both
+      # ExtensionProvisioner (convergence) and Verify (readiness), so
+      # the two can never drift.
+      module ExtensionProjection
+        RECEIPT_NAME = ".ace-lab-extension-projection.json"
+
+        module_function
+
+        # The installed gem's own tree at the EXACT declared version.
+        # @return [String, nil] the handbook/extensions directory or nil
+        #   when the gem (or its extensions tree) is not installed
+        def gem_source_root(gem_home, name, version)
+          candidate = File.join(gem_home, "gems", "#{name}-#{version}")
+          extensions = File.join(candidate, "handbook", "extensions")
+          File.directory?(extensions) ? extensions : nil
+        end
+
+        # Relative path → absolute source file for every file under the
+        # gem's handbook/extensions tree (e.g. "ace-wake/index.js").
+        # @return [Hash<String, String>]
+        def source_files(source_root)
+          Dir.glob(File.join(source_root, "**", "*")).select { |path| File.file?(path) }
+            .to_h { |path| [path.delete_prefix("#{source_root}/"), path] }
+        end
+
+        # Resolve and fully validate a projection destination before
+        # anything is written or verified (the provider_syncer
+        # validate_projection_destination posture): every path
+        # component under the projection directory must be a directory
+        # or creatable — a symlinked component could redirect the
+        # write outside the extensions directory, so it is refused.
+        # @param output_dir [String] manifest-declared extension dir
+        # @param relative_path [String] receipt-relative file path
+        # @return [String] the validated absolute destination
+        # @raise [Ace::Lab::Error] invalid or escaping destination
+        def validate_destination!(output_dir, relative_path)
+          segments = relative_path.to_s.split(File::SEPARATOR)
+          if segments.empty? || segments.any? { |segment| segment.empty? || segment == "." || segment == ".." }
+            raise Ace::Lab::Error, "cannot project #{relative_path.inspect}: invalid destination path"
+          end
+
+          begin
+            current = Pathname.new(File.realpath(output_dir))
+          rescue Errno::ENOENT
+            # the projection directory itself does not exist yet — no
+            # component below it can escape
+            return File.join(output_dir, *segments)
+          end
+          segments.each_with_index do |segment, index|
+            current = current.join(segment)
+            if File.symlink?(current.to_s)
+              raise Ace::Lab::Error,
+                "cannot project #{relative_path} into #{output_dir}: a symlinked path component " \
+                  "would escape the projection directory"
+            end
+            # The FINAL segment is the file itself — only intermediate
+            # components must be directories (compare by position, not
+            # value: "a/a/index.js" repeats "a" legitimately).
+            next if index == segments.size - 1
+
+            if !current.directory? && File.exist?(current.to_s)
+              raise Ace::Lab::Error,
+                "cannot project #{relative_path} into #{output_dir}: #{current} exists and is not a directory"
+            end
+          end
+          if File.directory?(current.to_s)
+            # Receipt ownership of a path never authorizes writing
+            # through a directory planted at that path — cp would
+            # reinterpret the destination as a container.
+            raise Ace::Lab::Error,
+              "cannot project #{relative_path} into #{output_dir}: #{current} exists and is a directory"
+          end
+          current.to_s
+        rescue Errno::ENOENT
+          raise Ace::Lab::Error, "cannot project #{relative_path} into #{output_dir}: projection directory vanished"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "extension_projection"
+require "etc"
+require "fileutils"
+require "json"
+
+module Ace
+  module Lab
+    module Molecules
+      # Projects harness extension assets from an INSTALLED gem's exact
+      # declared version into the manifest-declared extension directory
+      # (task 8xs.t.pu0.0): the manual host-lane copy of the ace-wake
+      # extension is replaced by a converged, repeatable projection.
+      #
+      # Source of truth is the installed gem tree itself —
+      # `<gem_home>/gems/<name>-<version>/handbook/extensions` — so the
+      # projection always matches the exact version the manifest
+      # declared (never the checkout, never a newer gem beside it).
+      # Each target directory carries a receipt
+      # (`.ace-lab-extension-projection.json`) recording the producing
+      # gem, version and file list; ONLY receipt-listed files are ever
+      # removed, so user-authored extensions in the same directory are
+      # never touched. The report names the version that WAS loaded
+      # before this run (`loaded_version`) and whether the projection
+      # changed (`restart_required`) — a changed projection means the
+      # running harness processes still hold the OLD extension; the
+      # installer REPORTS the restart need, it never restarts an
+      # executor on its own.
+      class ExtensionProvisioner
+        RECEIPT_NAME = ExtensionProjection::RECEIPT_NAME
+        FILE_MODE = 0o644
+        DIR_MODE = 0o755
+
+        # @param gem_home [String] target runtime the gems were
+        #   converged into
+        # @param dry_run [Boolean] predict without writing
+        # @param account_lookup [Proc, nil] passwd lookup seam for the
+        #   declared accounts (projection ownership convergence)
+        def initialize(gem_home:, dry_run: false, account_lookup: nil)
+          @gem_home = gem_home
+          @dry_run = dry_run
+          @account_lookup = account_lookup || method(:lookup_passwd)
+        end
+
+        # @param extensions [Array<Hash>] normalized manifest gemset
+        #   extensions entries ({"gem" =>, "path" =>, "account" =>})
+        # @param gems [Array<Hash>] declared gem set (name/version)
+        # @return [Array<Hash>] one report per entry:
+        #   {extension:, gem:, version:, path:, account:, status:,
+        #    loaded_version:, restart_required:, files:, message:}
+        def call(extensions:, gems:)
+          extensions.map do |entry|
+            converge(entry, gems)
+          end
+        end
+
+        private
+
+        def converge(entry, gems)
+          declared = gems.find { |gem| gem["name"] == entry["gem"] }
+          version = declared && declared["version"]
+          source = version && ExtensionProjection.gem_source_root(@gem_home, entry["gem"], version)
+
+          if source.nil?
+            # Fresh-lab dry run (the gem phase predicts would_install
+            # for the same missing gem): predict the projection the
+            # converged gem would feed instead of reporting a failure
+            # the wet run would not produce.
+            if @dry_run
+              return entry_report(entry, version, "would_project", nil, true, [])
+            end
+            return failed(entry, version,
+              "gem '#{entry["gem"]}' is not installed in runtime '#{@gem_home}' at declared " \
+                "version '#{version}'; converge the gemset first (ace-lab install)")
+          end
+
+          expected = ExtensionProjection.source_files(source)
+          if expected.empty?
+            return failed(entry, version,
+              "gem '#{entry["gem"]}' #{version} carries no handbook/extensions tree")
+          end
+
+          output_dir = entry["path"]
+          escape = projection_escape_reason(output_dir, expected.keys)
+          return failed(entry, version, escape) if escape
+
+          receipt = read_receipt(output_dir)
+          loaded_version = receipt && receipt["gem"] == entry["gem"] ? receipt["version"] : nil
+
+          changed = projection_changed?(output_dir, expected, receipt, version)
+          if !changed
+            converge_modes(output_dir, expected, entry)
+            return entry_report(entry, version, "unchanged", loaded_version, false,
+              receipt ? receipt.fetch("files") : expected.keys)
+          end
+          # dry-run predicts the projection (restart needed) without
+          # writing anything
+          return entry_report(entry, version, "projected", loaded_version, true, expected.keys) if @dry_run
+
+          project(output_dir, expected, entry, version)
+          entry_report(entry, version, "projected", loaded_version, true, expected.keys)
+        rescue SystemCallError => e
+          failed(entry, version,
+            "extension projection into '#{output_dir}' failed (#{e.class.name}); " \
+              "rerun ace-lab prepare with sudo or adjust ownership manually")
+        end
+
+        def failed(entry, version, message)
+          entry_report(entry, version, "failed", nil, false, [])
+            .merge("message" => message)
+        end
+
+        def entry_report(entry, version, status, loaded_version, restart_required, files)
+          {"extension" => entry["gem"], "gem" => entry["gem"], "version" => version,
+           "path" => entry["path"], "account" => entry["account"], "status" => status,
+           "loaded_version" => loaded_version, "restart_required" => restart_required,
+           "files" => files, "message" => nil}
+        end
+
+        # Refuse a destination that escapes the projection directory
+        # through a symlinked component BEFORE anything is written (the
+        # provider_syncer validate_projection_destination posture).
+        def projection_escape_reason(output_dir, relative_paths)
+          relative_paths.each { |relative| ExtensionProjection.validate_destination!(output_dir, relative) }
+          nil
+        rescue Ace::Lab::Error => e
+          e.message
+        end
+
+        # A projection changed when the receipt is absent, names a
+        # different version, lists a different file set, or any
+        # expected file's content differs on disk.
+        def projection_changed?(output_dir, expected, receipt, version)
+          return true if receipt.nil?
+          return true if receipt["version"] != version
+          return true unless receipt.fetch("files", []).sort == expected.keys.sort
+
+          expected.any? do |relative, source|
+            target = File.join(output_dir, relative)
+            !File.file?(target) || !FileUtils.compare_file(source, target)
+          end
+        end
+
+        def project(output_dir, expected, entry, version)
+          FileUtils.mkdir_p(output_dir)
+          expected.each do |relative, source|
+            target = File.join(output_dir, relative)
+            FileUtils.mkdir_p(File.dirname(target))
+            FileUtils.cp(source, target)
+          end
+
+          # Only receipt-owned files no longer in the projection are
+          # removed; a removal that fails keeps its receipt entry so a
+          # later run retries it (user-authored extensions are never
+          # touched).
+          previous = read_receipt(output_dir)&.fetch("files", []) || []
+          retained = previous.filter_map do |relative|
+            target = File.join(output_dir, relative)
+            next relative if expected.key?(relative)
+
+            FileUtils.rm_f(target)
+            File.exist?(target) ? relative : nil
+          end
+
+          write_receipt(output_dir, entry, version, (expected.keys + retained).sort)
+          converge_modes(output_dir, expected, entry)
+        end
+
+        # Mode/ownership convergence (the key-provisioner posture):
+        # projected files carry owner read/write plus world read
+        # (0644), projection directories 0755, and both are owned by
+        # the declared account whenever the passwd lookup resolves it —
+        # so the target executor can always read its extensions.
+        def converge_modes(output_dir, expected, entry)
+          account = @account_lookup.call(entry["account"])
+          targets = expected.keys.map { |relative| File.join(output_dir, relative) }
+          targets << File.join(output_dir, RECEIPT_NAME)
+          targets.each do |target|
+            next unless File.file?(target)
+
+            FileUtils.chmod(FILE_MODE, target)
+            FileUtils.chown(account.uid, account.gid, target) if account
+          end
+          root = File.realpath(output_dir)
+          dirs = expected.keys.filter_map do |relative|
+            File.dirname(File.join(root, relative)) if relative.include?(File::SEPARATOR)
+          end.uniq
+          until dirs.empty?
+            dir = dirs.pop
+            FileUtils.chmod(DIR_MODE, dir)
+            FileUtils.chown(account.uid, account.gid, dir) if account
+            parent = File.dirname(dir)
+            dirs << parent if dir != root && parent.start_with?("#{root}/") && !dirs.include?(parent) && parent != root
+          end
+        end
+
+        def write_receipt(output_dir, entry, version, files)
+          document = {
+            "gem" => entry["gem"], "version" => version,
+            "projected_at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "files" => files.sort
+          }
+          File.write(File.join(output_dir, RECEIPT_NAME), JSON.pretty_generate(document))
+        end
+
+        def read_receipt(output_dir)
+          path = File.join(output_dir, RECEIPT_NAME)
+          return nil unless File.file?(path)
+
+          document = JSON.parse(File.read(path))
+          document.is_a?(Hash) ? document : nil
+        rescue JSON::ParserError, Errno::EACCES
+          nil
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end