feat(install): Improve authentication handling and credential masking (#4948)

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Ruben Arts <[email protected]>

Author: 3 people

docs/installation.md

@@ -128,6 +128,7 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
     | `PIXI_ARCH`          | The architecture the Pixi version was built for.                                   | `uname -m`            |
     | `PIXI_NO_PATH_UPDATE`| If set the `$PATH` will not be updated to add `pixi` to it.                        |                       |
     | `PIXI_DOWNLOAD_URL`  | Overrides the download URL for the Pixi binary (useful for mirrors or custom builds). | GitHub releases, e.g. [linux-64](https://github.com/prefix-dev/pixi/releases/latest/download/pixi-x86_64-unknown-linux-musl.tar.gz)       |
+    | `NETRC`              | Path to a custom `.netrc` file for authentication with private repositories.       |                       |
     | `TMP_DIR`            | The temporary directory the script uses to download to and unpack the binary from. | `/tmp`                |
 
     For example, on Apple Silicon, you can force the installation of the x86 version:
@@ -139,6 +140,35 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
     curl -fsSL https://pixi.sh/install.sh | PIXI_VERSION=v0.18.0 bash
     ```
 
+    #### Using `.netrc` for Authentication
+
+    If you need to download Pixi from a private repository that requires authentication, you can use a `.netrc` file instead of hardcoding credentials in the `PIXI_DOWNLOAD_URL`.
+
+    The install script automatically uses `.netrc` for authentication with `curl` and `wget`. By default, it looks for `~/.netrc`. You can specify a custom location using the `NETRC` environment variable:
+
+    ```shell
+    # Use the default ~/.netrc file
+    curl -fsSL https://pixi.sh/install.sh | PIXI_DOWNLOAD_URL=https://private.example.com/pixi-latest.tar.gz bash
+    ```
+
+    ```shell
+    # Use a custom .netrc file
+    curl -fsSL https://pixi.sh/install.sh | NETRC=/path/to/custom/.netrc PIXI_DOWNLOAD_URL=https://private.example.com/pixi-latest.tar.gz bash
+    ```
+
+    Your `.netrc` file should contain credentials in the following format:
+    ```
+    machine private.example.com
+    login your-username
+    password your-token-or-password
+    ```
+
+    !!! tip "Security Recommendation"
+        Using `.netrc` is more secure than embedding credentials directly in the `PIXI_DOWNLOAD_URL` (e.g., `https://user:[email protected]/file`), as it keeps credentials separate from the URL and prevents them from appearing in logs or process listings.
+
+    !!! tip "Security Note"
+        The install script automatically masks any credentials embedded in the download URL when displaying messages, replacing them with `***:***@` to prevent credentials from appearing in logs or console output.
+
 === "Windows"
 
     The installation script has several options that can be manipulated through environment variables.
@@ -155,6 +185,17 @@ its [compile steps](https://github.com/conda/rattler/tree/main#give-it-a-try).
     $env:PIXI_VERSION='v0.18.0'; powershell -ExecutionPolicy Bypass -Command "iwr -useb https://pixi.sh/install.ps1 | iex"
     ```
 
+    #### Authentication for Private Repositories
+
+    If you need to download Pixi from a private repository that requires authentication, you can embed credentials in the `PIXI_DOWNLOAD_URL`. The install script will automatically mask credentials in its output for security.
+
+    ```powershell
+    $env:PIXI_DOWNLOAD_URL='https://username:[email protected]/pixi-latest.zip'; powershell -ExecutionPolicy Bypass -Command "iwr -useb https://pixi.sh/install.ps1 | iex"
+    ```
+
+    !!! tip "Security Note"
+        The PowerShell install script automatically masks any credentials embedded in the download URL when displaying messages, replacing them with `***:***@` to prevent credentials from appearing in logs or console output.
+
 ## Autocompletion
 
 To get autocompletion follow the instructions for your shell.

install/install.ps1

@@ -33,6 +33,14 @@ param (
 
 Set-StrictMode -Version Latest
 
+function Mask-Credentials {
+    param(
+        [string] $Url
+    )
+    # Replace username:password@ pattern with ***:***@
+    return $Url -replace '://[^:@/]+:[^@/]+@', '://***:***@'
+}
+
 function Publish-Env {
     if (-not ("Win32.NativeMethods" -as [Type])) {
         Add-Type -Namespace Win32 -Name NativeMethods -MemberDefinition @"
@@ -176,7 +184,7 @@ if ($Env:PIXI_DOWNLOAD_URL) {
 $BinDir = Join-Path $PixiHome 'bin'
 
 Write-Host "This script will automatically download and install Pixi ($PixiVersion) for you."
-Write-Host "Getting it from this url: $DOWNLOAD_URL"
+Write-Host "Getting it from this url: $(Mask-Credentials $DOWNLOAD_URL)"
 Write-Host "The binary will be installed into '$BinDir'"
 
 $TEMP_FILE = [System.IO.Path]::GetTempFileName()
@@ -195,7 +203,7 @@ try {
     # Extract pixi from the downloaded zip file
     Expand-Archive -Path $ZIP_FILE -DestinationPath $BinDir -Force
 } catch {
-    Write-Host "Error: '$DOWNLOAD_URL' is not available or failed to download"
+    Write-Host "Error: '$(Mask-Credentials $DOWNLOAD_URL)' is not available or failed to download"
     exit 1
 } finally {
     Remove-Item -Path $ZIP_FILE

install/install.sh

@@ -3,6 +3,27 @@ set -eu
 # Version: v0.59.0
 
 __wrap__() {
+    # Function to mask username and password in URLs for safe printing
+    # Usage: mask_credentials "url"
+    # Returns the URL with credentials replaced by ***:***@
+    #
+    # [^:@/]+ - This matches the username part:
+    #   - [^:@/] means "any character EXCEPT :, @, or /"
+    #   - + means "one or more of these characters"
+    #   - So it captures everything up until it hits a colon, at-sign, or slash
+    #   - : - Matches the literal colon that separates username from password
+    #
+    # [^@/]+ - This matches the password part:
+    #   - [^@/] means "any character EXCEPT @ or /"
+    #   - + means "one or more of these characters"
+    #   - So it captures everything after the colon until it hits an at-sign or slash
+    #   - @ - Matches the literal at-sign that
+    mask_credentials() {
+        URL="$1"
+        # Use sed to replace username:password@ pattern with ***:***@
+        echo "$URL" | sed -E 's|://[^:@/]+:[^@/]+@|://***:***@|g'
+    }
+
     VERSION="${PIXI_VERSION:-latest}"
     PIXI_HOME="${PIXI_HOME:-$HOME/.pixi}"
     case "$PIXI_HOME" in
@@ -44,7 +65,7 @@ __wrap__() {
         DOWNLOAD_URL="${PIXI_DOWNLOAD_URL:-${REPOURL%/}/releases/download/v${VERSION#v}/${BINARY}${EXTENSION-}}"
     fi
 
-    printf "This script will automatically download and install Pixi (%s) for you.\nGetting it from this url: %s\n" "$VERSION" "$DOWNLOAD_URL"
+    printf "This script will automatically download and install Pixi (%s) for you.\nGetting it from this url: %s\n" "$VERSION" "$(mask_credentials "$DOWNLOAD_URL")"
 
     HAVE_CURL=false
     HAVE_CURL_8_8_0=false
@@ -93,33 +114,46 @@ __wrap__() {
         WGET_OPTIONS="--show-progress"
     fi
 
+    # Use .netrc for authentication - prioritize NETRC env var over default location
+    if [ -n "${NETRC:-}" ]; then
+        CURL_OPTIONS="$CURL_OPTIONS --netrc-file $NETRC"
+        WGET_OPTIONS="$WGET_OPTIONS --netrc-file=$NETRC"
+    elif [ -f "$HOME/.netrc" ]; then
+        CURL_OPTIONS="$CURL_OPTIONS --netrc"
+        WGET_OPTIONS="$WGET_OPTIONS --netrc"
+    fi
+
     if $HAVE_CURL; then
         CURL_ERR=0
         HTTP_CODE="$(curl -SL $CURL_OPTIONS "$DOWNLOAD_URL" --output "$TEMP_FILE" --write-out "%{http_code}")" || CURL_ERR=$?
         case "$CURL_ERR" in
         35 | 53 | 54 | 59 | 66 | 77)
             if ! $HAVE_WGET; then
-                echo "error: when download '${DOWNLOAD_URL}', curl has some local ssl problems with error $CURL_ERR" >&2
+                echo "error: when download '$(mask_credentials "$DOWNLOAD_URL")', curl has some local ssl problems with error $CURL_ERR" >&2
                 exit 1
             fi
             # fallback to wget
             ;;
         0)
-            if [ "${HTTP_CODE}" -lt 200 ] || [ "${HTTP_CODE}" -gt 299 ]; then
-                echo "error: '${DOWNLOAD_URL}' is not available" >&2
+            if [ "${HTTP_CODE}" -eq 401 ]; then
+                echo "error: authentication failed when downloading '$(mask_credentials "$DOWNLOAD_URL")'" >&2
+                echo "       Check your .netrc file, NETRC environment variable, or the hardcoded credentials in PIXI_DOWNLOAD_URL." >&2
+                exit 1
+            elif [ "${HTTP_CODE}" -lt 200 ] || [ "${HTTP_CODE}" -gt 299 ]; then
+                echo "error: '$(mask_credentials "$DOWNLOAD_URL")' is not available (HTTP ${HTTP_CODE})" >&2
                 exit 1
             fi
             HAVE_WGET=false # download success, skip wget
             ;;
         *)
-            echo "error: when download '${DOWNLOAD_URL}', curl fails with with error $CURL_ERR" >&2
+            echo "error: when download '$(mask_credentials "$DOWNLOAD_URL")', curl fails with error $CURL_ERR" >&2
             exit 1
             ;;
         esac
     fi
 
     if $HAVE_WGET && ! wget $WGET_OPTIONS --output-document="$TEMP_FILE" "$DOWNLOAD_URL"; then
-        echo "error: '${DOWNLOAD_URL}' is not available" >&2
+        echo "error: '$(mask_credentials "$DOWNLOAD_URL")' is not available" >&2
         exit 1
     fi