From 5a921f99e2d8a1dc87161b46604facedfc3ac8bf Mon Sep 17 00:00:00 2001
From: Mike McQuaid <mike@mikemcquaid.com>
Date: Tue, 7 Jan 2025 15:31:06 +0000
Subject: [PATCH] Add support for Homebrew wrappers

Allow the ability for a system administrator to use
`HOMEBREW_BREW_WRAPPER` and `HOMEBREW_FORCE_BREW_WRAPPER` variables to
enforce the usage of a particular `brew` command for non-trivial (e.g.
`brew --prefix` is considered trivial, it doesn't need to write to the
prefix) Homebrew commands.

This also introduces a `HOMEBREW_ORIGINAL_BREW_FILE` variable for some
internal usage; `HOMEBREW_BREW_FILE` was being used internally for
both "how should we shell out to Homebrew" and "what should we use
to check permissions on Homebrew". `HOMEBREW_ORIGINAL_BREW_FILE` is
now used just for the latter case.

Inspired by conversation in
https://github.com/Homebrew/homebrew-bundle/pull/1551 which suggested
this was worth fixing in wider than just `brew bundle`.
---
 Library/Homebrew/brew.sh                      | 50 ++++++++++++++++---
 Library/Homebrew/env_config.rb                |  7 +++
 Library/Homebrew/formula.rb                   |  2 +-
 Library/Homebrew/global.rb                    |  2 +-
 Library/Homebrew/mktemp.rb                    |  4 +-
 Library/Homebrew/sandbox.rb                   |  2 +-
 .../sorbet/rbi/dsl/homebrew/env_config.rbi    |  6 +++
 Library/Homebrew/startup/config.rb            |  5 ++
 Library/Homebrew/style.rb                     |  2 +-
 .../test/support/lib/startup/config.rb        |  1 +
 bin/brew                                      | 35 +++++++++++--
 11 files changed, 98 insertions(+), 18 deletions(-)

diff --git a/Library/Homebrew/brew.sh b/Library/Homebrew/brew.sh
index 7c59fd881e8aa..31314fd3c83e2 100644
--- a/Library/Homebrew/brew.sh
+++ b/Library/Homebrew/brew.sh
@@ -127,12 +127,6 @@ case "$1" in
     homebrew-shellenv "$1"
     exit 0
     ;;
-  setup-ruby)
-    source "${HOMEBREW_LIBRARY}/Homebrew/cmd/setup-ruby.sh"
-    shift
-    homebrew-setup-ruby "$1"
-    exit 0
-    ;;
 esac
 
 source "${HOMEBREW_LIBRARY}/Homebrew/help.sh"
@@ -184,8 +178,50 @@ case "$@" in
     ;;
 esac
 
+source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
+if [[ -n "${HOMEBREW_FORCE_BREW_WRAPPER}" ]]
+then
+  if [[ -z "${HOMEBREW_BREW_WRAPPER:-}" ]]
+  then
+    odie <<EOS
+HOMEBREW_FORCE_BREW_WRAPPER was set to
+  ${HOMEBREW_FORCE_BREW_WRAPPER}
+but HOMEBREW_BREW_WRAPPER was unset. This indicates that you are running
+  ${HOMEBREW_BREW_FILE}
+directly but should instead run
+  ${HOMEBREW_FORCE_BREW_WRAPPER}
+EOS
+  elif [[ "${HOMEBREW_FORCE_BREW_WRAPPER:-}" != "${HOMEBREW_BREW_WRAPPER:-}" ]]
+  then
+    odie <<EOS
+HOMEBREW_FORCE_BREW_WRAPPER was set to
+  ${HOMEBREW_FORCE_BREW_WRAPPER}
+but HOMEBREW_BREW_WRAPPER was set to
+  ${HOMEBREW_BREW_WRAPPER}
+This indicates that you are running
+  ${HOMEBREW_BREW_FILE}
+directly but should instead run:
+  ${HOMEBREW_FORCE_BREW_WRAPPER}
+EOS
+  fi
+fi
+
+# commands that take a single or no arguments and need to write to HOMEBREW_PREFIX.
+# HOMEBREW_LIBRARY set by bin/brew
+# shellcheck disable=SC2154
+# doesn't need a default case as other arguments handled elsewhere.
+# shellcheck disable=SC2249
+case "$1" in
+  setup-ruby)
+    source "${HOMEBREW_LIBRARY}/Homebrew/cmd/setup-ruby.sh"
+    shift
+    homebrew-setup-ruby "$1"
+    exit 0
+    ;;
+esac
+
 #####
-##### Next, define all helper functions.
+##### Next, define all other helper functions.
 #####
 source "${HOMEBREW_LIBRARY}/Homebrew/utils/helpers.sh"
 
diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
index 180c6d5b83602..742408b818e0f 100644
--- a/Library/Homebrew/env_config.rb
+++ b/Library/Homebrew/env_config.rb
@@ -87,6 +87,9 @@ module EnvConfig
         description: "Use this URL as the Homebrew/brew `git`(1) remote.",
         default:     HOMEBREW_BREW_DEFAULT_GIT_REMOTE,
       },
+      HOMEBREW_BREW_WRAPPER:                     {
+        description: "If set, use wrapper to call `brew` rather than auto-detecting it.",
+      },
       HOMEBREW_BROWSER:                          {
         description:  "Use this as the browser when opening project homepages.",
         default_text: "`$BROWSER` or the OS's default browser.",
@@ -242,6 +245,10 @@ module EnvConfig
                      "Automatically set if the system version of `git` is too old.",
         boolean:     true,
       },
+      HOMEBREW_FORCE_BREW_WRAPPER:               {
+        description: "If set, require `HOMEBREW_BREW_WRAPPER` to be set to the same value as " \
+                     "`HOMEBREW_FORCE_BREW_WRAPPER` for non-trivial `brew` commands.",
+      },
       HOMEBREW_FORCE_VENDOR_RUBY:                {
         description: "If set, always use Homebrew's vendored, relocatable Ruby version even if the system version " \
                      "of Ruby is new enough.",
diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index b715226c224a9..cddc9f57d7429 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -1499,7 +1499,7 @@ def skip_clean?(path)
   # @see .link_overwrite
   def link_overwrite?(path)
     # Don't overwrite files not created by Homebrew.
-    return false if path.stat.uid != HOMEBREW_BREW_FILE.stat.uid
+    return false if path.stat.uid != HOMEBREW_ORIGINAL_BREW_FILE.stat.uid
 
     # Don't overwrite files belong to other keg except when that
     # keg's formula is deleted.
diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb
index 46ab618ab5231..3aeedb202cc96 100644
--- a/Library/Homebrew/global.rb
+++ b/Library/Homebrew/global.rb
@@ -100,7 +100,7 @@ def running_as_root?
     end
 
     def owner_uid
-      @owner_uid ||= HOMEBREW_BREW_FILE.stat.uid
+      @owner_uid ||= HOMEBREW_ORIGINAL_BREW_FILE.stat.uid
     end
 
     def running_as_root_but_not_owned_by_root?
diff --git a/Library/Homebrew/mktemp.rb b/Library/Homebrew/mktemp.rb
index 181f1d3aadba0..d01edae9a594b 100644
--- a/Library/Homebrew/mktemp.rb
+++ b/Library/Homebrew/mktemp.rb
@@ -67,8 +67,8 @@ def run(chdir: true, &_block)
     # Reference from `man 2 open`
     # > When a new file is created, it is given the group of the directory which
     # contains it.
-    group_id = if HOMEBREW_BREW_FILE.grpowned?
-      HOMEBREW_BREW_FILE.stat.gid
+    group_id = if HOMEBREW_ORIGINAL_BREW_FILE.grpowned?
+      HOMEBREW_ORIGINAL_BREW_FILE.stat.gid
     else
       Process.gid
     end
diff --git a/Library/Homebrew/sandbox.rb b/Library/Homebrew/sandbox.rb
index d668288b0f71c..6b3ad1dabde5f 100644
--- a/Library/Homebrew/sandbox.rb
+++ b/Library/Homebrew/sandbox.rb
@@ -103,7 +103,7 @@ def allow_write_log(formula)
 
   sig { void }
   def deny_write_homebrew_repository
-    deny_write path: HOMEBREW_BREW_FILE
+    deny_write path: HOMEBREW_ORIGINAL_BREW_FILE
     if HOMEBREW_PREFIX.to_s == HOMEBREW_REPOSITORY.to_s
       deny_write_path HOMEBREW_LIBRARY
       deny_write_path HOMEBREW_REPOSITORY/".git"
diff --git a/Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi b/Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi
index e86443e2a7a62..2cdeb8ed6aba5 100644
--- a/Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi
+++ b/Library/Homebrew/sorbet/rbi/dsl/homebrew/env_config.rbi
@@ -49,6 +49,9 @@ module Homebrew::EnvConfig
     sig { returns(String) }
     def brew_git_remote; end
 
+    sig { returns(T.nilable(::String)) }
+    def brew_wrapper; end
+
     sig { returns(T.nilable(::String)) }
     def browser; end
 
@@ -139,6 +142,9 @@ module Homebrew::EnvConfig
     sig { returns(T::Boolean) }
     def force_api_auto_update?; end
 
+    sig { returns(T::Boolean) }
+    def force_brew_wrapper?; end
+
     sig { returns(T::Boolean) }
     def force_brewed_ca_certificates?; end
 
diff --git a/Library/Homebrew/startup/config.rb b/Library/Homebrew/startup/config.rb
index 7ef65a1eaae05..225a3a04a7c02 100644
--- a/Library/Homebrew/startup/config.rb
+++ b/Library/Homebrew/startup/config.rb
@@ -4,6 +4,11 @@
 raise "HOMEBREW_BREW_FILE was not exported! Please call bin/brew directly!" unless ENV["HOMEBREW_BREW_FILE"]
 
 # Path to `bin/brew` main executable in `HOMEBREW_PREFIX`
+# Used for e.g. permissions checks.
+HOMEBREW_ORIGINAL_BREW_FILE = Pathname(ENV.fetch("HOMEBREW_ORIGINAL_BREW_FILE")).freeze
+
+# Path to the executable that should be used to run `brew`.
+# This may be HOMEBREW_ORIGINAL_BREW_FILE or HOMEBREW_BREW_WRAPPER.
 HOMEBREW_BREW_FILE = Pathname(ENV.fetch("HOMEBREW_BREW_FILE")).freeze
 
 # Where we link under
diff --git a/Library/Homebrew/style.rb b/Library/Homebrew/style.rb
index 493d4fc37d4fb..e25271138b5d6 100644
--- a/Library/Homebrew/style.rb
+++ b/Library/Homebrew/style.rb
@@ -304,7 +304,7 @@ def self.json_result!(result)
 
     def self.shell_scripts
       [
-        HOMEBREW_BREW_FILE,
+        HOMEBREW_ORIGINAL_BREW_FILE,
         HOMEBREW_REPOSITORY/"completions/bash/brew",
         HOMEBREW_REPOSITORY/"Dockerfile",
         *HOMEBREW_REPOSITORY.glob(".devcontainer/**/*.sh"),
diff --git a/Library/Homebrew/test/support/lib/startup/config.rb b/Library/Homebrew/test/support/lib/startup/config.rb
index a5c858723bceb..4a1019b265242 100644
--- a/Library/Homebrew/test/support/lib/startup/config.rb
+++ b/Library/Homebrew/test/support/lib/startup/config.rb
@@ -3,6 +3,7 @@
 
 raise "HOMEBREW_BREW_FILE was not exported! Please call bin/brew directly!" unless ENV["HOMEBREW_BREW_FILE"]
 
+HOMEBREW_ORIGINAL_BREW_FILE = Pathname.new(ENV.fetch("HOMEBREW_ORIGINAL_BREW_FILE")).freeze
 HOMEBREW_BREW_FILE = Pathname.new(ENV.fetch("HOMEBREW_BREW_FILE")).freeze
 
 TEST_TMPDIR = ENV.fetch("HOMEBREW_TEST_TMPDIR") do |k|
diff --git a/bin/brew b/bin/brew
index 14c135f0f0c23..294091fe816a6 100755
--- a/bin/brew
+++ b/bin/brew
@@ -116,6 +116,23 @@ unset BREW_FILE_DIRECTORY
 # keg_relocate.rb, formula_cellar_checks.rb, and test/global_spec.rb need to change.
 HOMEBREW_LIBRARY="${HOMEBREW_REPOSITORY}/Library"
 
+# Use HOMEBREW_BREW_WRAPPER if set.
+export HOMEBREW_ORIGINAL_BREW_FILE="${HOMEBREW_BREW_FILE}"
+if [[ -n "${HOMEBREW_BREW_WRAPPER:-}" ]]
+then
+  HOMEBREW_BREW_FILE="${HOMEBREW_BREW_WRAPPER}"
+fi
+
+# These variables are exported in this file and are not allowed to be overridden by the user.
+BIN_BREW_EXPORTED_VARS=(
+  HOMEBREW_BREW_FILE
+  HOMEBREW_PREFIX
+  HOMEBREW_REPOSITORY
+  HOMEBREW_LIBRARY
+  HOMEBREW_USER_CONFIG_HOME
+  HOMEBREW_ORIGINAL_BREW_FILE
+)
+
 # Load Homebrew's variable configuration files from disk.
 export_homebrew_env_file() {
   local env_file
@@ -126,6 +143,15 @@ export_homebrew_env_file() {
   do
     # only load HOMEBREW_* lines
     [[ "${line}" = "HOMEBREW_"* ]] || continue
+
+    # forbid overriding variables that are set in this file
+    local invalid_variable
+    for VAR in "${BIN_BREW_EXPORTED_VARS[@]}"
+    do
+      [[ "${line}" = "${VAR}"* ]] && invalid_variable="${VAR}"
+    done
+    [[ -n "${invalid_variable}" ]] && continue
+
     export "${line?}"
   done <"${env_file}"
 }
@@ -212,11 +238,10 @@ done
 
 unset VAR VAR_NEW MANPAGE_VARS USED_BY_HOMEBREW_VARS
 
-export HOMEBREW_BREW_FILE
-export HOMEBREW_PREFIX
-export HOMEBREW_REPOSITORY
-export HOMEBREW_LIBRARY
-export HOMEBREW_USER_CONFIG_HOME
+for VAR in "${BIN_BREW_EXPORTED_VARS[@]}"
+do
+  export "${VAR?}"
+done
 
 # set from user environment
 # shellcheck disable=SC2154