feat(bootstrap): fold enterprise mirror follow-ups

Salvage the apm-review-panel follow-up delta that landed after PR #1733 was squash-merged for issue #1680.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danielmeppiel

CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   of `~/.hermes/config.yaml` (written atomically with `0o600` perms, preserving
   unrelated config keys and refusing to overwrite a malformed file). `HERMES_HOME`
   overrides the Hermes home directory. See the [Hermes integration guide](https://microsoft.github.io/apm/integrations/hermes/).
-- Enterprise bootstrap mirror mode lets `install.sh`, `install.ps1`, and `apm self-update` use internal release, installer, and PyPI mirrors with fail-closed public fallback, and closes #1680. (#1733)
+- Enterprise bootstrap mirror mode lets `install.sh`, `install.ps1`, and `apm self-update` use `APM_RELEASE_METADATA_URL`, `APM_RELEASE_BASE_URL`, `APM_INSTALLER_BASE_URL`, `APM_PYPI_INDEX_URL`, and `APM_NO_DIRECT_FALLBACK` for internal release, installer, and PyPI mirrors with fail-closed public fallback, and closes #1680. (#1733)
 
 ### Fixed
 

docs/src/content/docs/getting-started/installation.md

@@ -102,7 +102,7 @@ jobs:
 
 ### Enterprise bootstrap mirror mode
 
-Mirror mode lets locked-down workstations install and update APM without direct public egress:
+APM ships native enterprise mirror support: five env vars route bootstrap traffic through internal hosts, with fail-closed mode ensuring no public fallback.
 
 ```bash
 export APM_INSTALLER_BASE_URL="https://artifactory.mycorp.example/generic/apm-install"
@@ -144,7 +144,7 @@ apm-releases/
 
 #### What fail-closed does and does not cover
 
-Fail-closed scoping keys off the public `github.com` default. The guard only blocks egress when the resolved host would be public GitHub (`github.com` / `api.github.com`), `aka.ms`, or public PyPI. It does **not** suppress egress to a custom `GITHUB_URL`: if you set a GHES host (for example `GITHUB_URL=https://github.corp.com`) together with `APM_NO_DIRECT_FALLBACK=1` and no release mirror, the installer still reaches that GHES host. This is intentional coexistence with GHES, but "no direct fallback" should not be read as "zero egress" -- it means "no fallback to public hosts". For true zero-egress, set the `APM_RELEASE_METADATA_URL` / `APM_RELEASE_BASE_URL` / `APM_INSTALLER_BASE_URL` / `APM_PYPI_INDEX_URL` mirrors so every request resolves to your internal hosts. The GitHub token is attached only when the request targets the canonical GitHub / configured GHES host; it is never sent to a mirror host.
+Fail-closed scoping keys off the public `github.com` default. The guard only blocks egress when the resolved host would be public GitHub (`github.com` / `api.github.com`), `aka.ms`, or public PyPI. It does **not** suppress egress to a custom `GITHUB_URL`: if you set a GHES host (for example `GITHUB_URL=https://github.corp.com`) together with `APM_NO_DIRECT_FALLBACK=1` and no release mirror, the installer still reaches that GHES host. This is intentional coexistence with GHES, but "no direct fallback" should not be read as "zero egress" -- it means "no fallback to public hosts". For true zero-egress, set the `APM_RELEASE_METADATA_URL` / `APM_RELEASE_BASE_URL` / `APM_INSTALLER_BASE_URL` / `APM_PYPI_INDEX_URL` mirrors so every request resolves to your internal hosts. When `APM_RELEASE_METADATA_URL` is unset, GHES metadata requests intentionally use the resolved GitHub token for that host; mirror metadata requests never receive it. The GitHub token is attached only when the request targets the canonical GitHub / configured GHES host, never a mirror host.
 
 Homebrew and Scoop mirror support is docs-only in this v0: mirror the tap or bucket with your package manager's normal enterprise controls, but the APM env vars above do not rewrite Homebrew or Scoop internals.
 
@@ -187,13 +187,17 @@ chmod +x .apm-mirror-smoke/bin/curl .apm-mirror-smoke/bin/pip .apm-mirror-smoke/
 python3 -m http.server 8765 --directory .apm-mirror-smoke/mirror > .apm-mirror-smoke/server.log 2>&1 &
 server_pid=$!
 trap 'kill "$server_pid" 2>/dev/null || true' EXIT
+set +e
 PATH="$PWD/.apm-mirror-smoke/bin:$PATH" \
   APM_INSTALLER_BASE_URL="http://127.0.0.1:8765/apm-install" \
   APM_RELEASE_METADATA_URL="http://127.0.0.1:8765/apm-releases/latest.json" \
   APM_RELEASE_BASE_URL="http://127.0.0.1:8765/apm-releases" \
   APM_PYPI_INDEX_URL="http://127.0.0.1:8765/pypi/simple" \
   APM_NO_DIRECT_FALLBACK=1 \
-  sh .apm-mirror-smoke/mirror/apm-install/install.sh || test $? -eq 1
+  sh .apm-mirror-smoke/mirror/apm-install/install.sh
+status=$?
+set -e
+test "$status" -ne 0
 ```
 
 For `apm self-update`, run `apm self-update --check` with the same env vars and verify your proxy, firewall, or CI egress logs show only the mirror host. Use a disposable runner for a full `apm self-update` because it executes the mirrored installer.

docs/src/content/docs/reference/cli/self-update.md

@@ -41,7 +41,7 @@ Some package-manager distributions (for example, Homebrew) disable self-update a
 |----------|---------|--------|
 | `APM_RELEASE_METADATA_URL` | _(unset)_ | Exact URL for mirrored release metadata, usually a static `latest.json` with at least `{"tag_name":"vX.Y.Z"}`. Overrides GitHub release metadata lookup. |
 | `APM_INSTALLER_BASE_URL` | _(unset)_ | Base URL containing `install.sh` and `install.ps1`. `apm self-update` downloads the platform script from this base. |
-| `APM_RELEASE_BASE_URL` | _(unset)_ | Base URL containing release assets at `{base}/{tag}/{asset}`. The downloaded installer subprocess inherits this value. |
+| `APM_RELEASE_BASE_URL` | _(unset)_ | Base URL containing release assets at `{base}/{tag}/{asset}`. Used when self-update runs the installer to fetch binary archives. |
 | `APM_PYPI_INDEX_URL` | _(unset)_ | PyPI-compatible index used by installer pip fallback. |
 | `APM_NO_DIRECT_FALLBACK` | _(unset)_ | Set to `1` to fail closed instead of using public GitHub, `aka.ms`, or PyPI fallback. |
 | `GITHUB_URL` | `https://github.com` | Legacy GitHub/GHES base URL. Still supported when mirror env vars are not set. |
@@ -61,9 +61,7 @@ apm self-update --check
 apm self-update
 ```
 
-With `APM_NO_DIRECT_FALLBACK=1`, missing or unreachable mirror settings are hard failures with a non-zero exit. APM does not fall back to public GitHub, `aka.ms`, or PyPI in that mode.
-
-Fail-closed scoping keys off the public `github.com` default: it blocks fallback to public hosts, not all egress. A custom `GITHUB_URL` (a GHES host) combined with `APM_NO_DIRECT_FALLBACK=1` and no release mirror still egresses to that GHES host -- this is intentional GHES coexistence. For zero public egress set the `APM_RELEASE_METADATA_URL` / `APM_RELEASE_BASE_URL` / `APM_INSTALLER_BASE_URL` / `APM_PYPI_INDEX_URL` mirrors. The GitHub token is sent only to the canonical GitHub / configured GHES host, never to a mirror host.
+With `APM_NO_DIRECT_FALLBACK=1`, missing or unreachable mirror settings are hard failures with a non-zero exit. For the full fail-closed scope, GHES token boundary, and no-egress smoke recipe, see [Enterprise bootstrap mirror mode](../../../getting-started/installation/#enterprise-bootstrap-mirror-mode).
 
 ## Options
 

install.ps1

@@ -479,9 +479,10 @@ if ($pinnedVersion) {
         exit 1
     }
     $latestUri = Get-ReleaseMetadataUri
+    $headers = if ($releaseMetadataUrl) { @{} } else { Get-AuthHeader }
     $metadataError = $null
     try {
-        $release = Invoke-RestMethod -Uri $latestUri
+        $release = Invoke-GitHubJson -Uri $latestUri -Headers $headers
     } catch {
         $metadataError = $_
     }

install.sh

@@ -97,7 +97,15 @@ is_truthy() {
 }
 
 is_public_github_url() {
-    [ "${GITHUB_URL%/}" = "https://github.com" ]
+    [ "${GITHUB_URL:-https://github.com}" = "https://github.com" ] || [ "${GITHUB_URL%/}" = "https://github.com" ]
+}
+
+fail_closed_error() {
+    _mirror_var="$1"
+    shift
+    echo -e "${RED}Error: APM_NO_DIRECT_FALLBACK is set, but $_mirror_var is not configured.${NC}"
+    echo "$*"
+    exit 1
 }
 
 join_url_path() {
@@ -190,9 +198,7 @@ try_pip_installation() {
         PIP_INSTALL_OK=0
         $PIP_CMD install --user --index-url "$APM_PYPI_INDEX_URL" apm-cli || PIP_INSTALL_OK=$?
     elif is_truthy "$APM_NO_DIRECT_FALLBACK"; then
-        echo -e "${RED}Error: APM_NO_DIRECT_FALLBACK is set, but APM_PYPI_INDEX_URL is not configured.${NC}"
-        echo "Set APM_PYPI_INDEX_URL to your internal PyPI proxy before using pip fallback."
-        return 1
+        fail_closed_error APM_PYPI_INDEX_URL "Set APM_PYPI_INDEX_URL to your internal PyPI proxy before using pip fallback."
     else
         PIP_INSTALL_OK=0
         $PIP_CMD install --user apm-cli || PIP_INSTALL_OK=$?
@@ -297,9 +303,7 @@ fi
 if [ -n "$VERSION" ]; then
     TAG_NAME="$VERSION"
     if is_truthy "$APM_NO_DIRECT_FALLBACK" && [ -z "$APM_RELEASE_BASE_URL" ] && is_public_github_url; then
-        echo -e "${RED}Error: APM_NO_DIRECT_FALLBACK is set, but APM_RELEASE_BASE_URL is not configured.${NC}"
-        echo "Set APM_RELEASE_BASE_URL to a mirror containing $TAG_NAME/$DOWNLOAD_BINARY."
-        exit 1
+        fail_closed_error APM_RELEASE_BASE_URL "Set APM_RELEASE_BASE_URL to a mirror containing $TAG_NAME/$DOWNLOAD_BINARY."
     fi
     DOWNLOAD_URL=$(release_asset_url "$TAG_NAME" "$DOWNLOAD_BINARY")
     echo -e "${GREEN}Version: $TAG_NAME${NC}"
@@ -311,9 +315,7 @@ if [ -z "$TAG_NAME" ]; then
 echo -e "${YELLOW}Fetching latest release information...${NC}"
 
 if is_truthy "$APM_NO_DIRECT_FALLBACK" && [ -z "$APM_RELEASE_METADATA_URL" ] && is_public_github_url; then
-    echo -e "${RED}Error: APM_NO_DIRECT_FALLBACK is set, but APM_RELEASE_METADATA_URL is not configured.${NC}"
-    echo "Set APM_RELEASE_METADATA_URL to mirrored latest.json, or set VERSION to a pinned release."
-    exit 1
+    fail_closed_error APM_RELEASE_METADATA_URL "Set APM_RELEASE_METADATA_URL to mirrored latest.json, or set VERSION to a pinned release."
 fi
 
 LATEST_RELEASE_URL=$(release_metadata_url)
@@ -397,9 +399,7 @@ fi
 # Use grep -o to extract just the matching portion (handles single-line JSON)
 TAG_NAME=$(echo "$LATEST_RELEASE" | grep -o '"tag_name": *"[^"]*"' | awk -F'"' '{print $4}')
 if is_truthy "$APM_NO_DIRECT_FALLBACK" && [ -z "$APM_RELEASE_BASE_URL" ] && is_public_github_url; then
-    echo -e "${RED}Error: APM_NO_DIRECT_FALLBACK is set, but APM_RELEASE_BASE_URL is not configured.${NC}"
-    echo "Set APM_RELEASE_BASE_URL to a mirror containing $TAG_NAME/$DOWNLOAD_BINARY."
-    exit 1
+    fail_closed_error APM_RELEASE_BASE_URL "Set APM_RELEASE_BASE_URL to a mirror containing $TAG_NAME/$DOWNLOAD_BINARY."
 fi
 DOWNLOAD_URL=$(release_asset_url "$TAG_NAME" "$DOWNLOAD_BINARY")
 

packages/apm-guide/.apm/skills/apm-usage/installation.md

@@ -69,15 +69,7 @@ irm https://aka.ms/apm-windows | iex
 
 ## Enterprise bootstrap mirrors
 
-Use these env vars to install and update APM through an internal mirror and fail closed when a public fallback would be required:
-
-| Variable | Purpose |
-|----------|---------|
-| `APM_INSTALLER_BASE_URL` | Base URL containing `install.sh` and `install.ps1`. |
-| `APM_RELEASE_METADATA_URL` | Exact URL for mirrored `latest.json` release metadata. |
-| `APM_RELEASE_BASE_URL` | Base URL for release assets at `{base}/{tag}/{asset}`. |
-| `APM_PYPI_INDEX_URL` | PyPI proxy used by installer pip fallback. |
-| `APM_NO_DIRECT_FALLBACK` | Set to `1` to block public GitHub, `aka.ms`, and PyPI fallback. |
+Set `APM_INSTALLER_BASE_URL`, `APM_RELEASE_METADATA_URL`, `APM_RELEASE_BASE_URL`, `APM_PYPI_INDEX_URL`, and `APM_NO_DIRECT_FALLBACK=1` to install and update APM through an internal mirror while failing closed on public fallback. The canonical variable table, GHES scoping note, and no-egress smoke recipe live in [installation.md](https://github.com/microsoft/apm/blob/main/docs/src/content/docs/getting-started/installation.md#enterprise-bootstrap-mirror-mode).
 
 ```bash
 export APM_INSTALLER_BASE_URL="https://artifactory.mycorp.example/generic/apm-install"
@@ -91,10 +83,6 @@ apm self-update --check
 
 For dependency installs after bootstrap, keep using `PROXY_REGISTRY_URL` and `PROXY_REGISTRY_ONLY=1`. Homebrew and Scoop mirroring is package-manager documentation only in v0; these env vars do not rewrite Homebrew or Scoop internals.
 
-Fail-closed scoping keys off the public `github.com` default: it blocks fallback to public hosts, not all egress. A custom `GITHUB_URL` (GHES host) plus `APM_NO_DIRECT_FALLBACK=1` and no release mirror still reaches that GHES host. Set the four mirror URLs for zero public egress. The GitHub token is attached only to the canonical GitHub / configured GHES host, never to a mirror host (symmetric across `install.sh` and `install.ps1`).
-
-No-egress smoke test: run the installer on a disposable runner with `curl` and `pip` wrappers (or an egress proxy) that deny `github.com`, `api.github.com`, `aka.ms`, `pypi.org`, `pythonhosted.org`, Homebrew, and Scoop upstreams. Wrapping `pip` keeps the proof honest about the PyPI fallback path. With all mirror env vars set, the only allowed outbound host should be your mirror. Run `apm self-update --check` under the same env vars and confirm proxy logs show only the mirror host.
-
 ## Troubleshooting
 
 - **macOS/Linux "command not found":** ensure your install directory (default `/usr/local/bin`) is in `$PATH`.

src/apm_cli/bootstrap_mirror.py

@@ -2,12 +2,14 @@
 
 import os
 
+from apm_cli.utils.path_security import PathTraversalError, validate_path_segments
+
 APM_RELEASE_BASE_URL = "APM_RELEASE_BASE_URL"
 APM_RELEASE_METADATA_URL = "APM_RELEASE_METADATA_URL"
 APM_INSTALLER_BASE_URL = "APM_INSTALLER_BASE_URL"
 APM_PYPI_INDEX_URL = "APM_PYPI_INDEX_URL"
 APM_NO_DIRECT_FALLBACK = "APM_NO_DIRECT_FALLBACK"
-VERSION = "VERSION"
+VERSION_ENV_VAR = "VERSION"
 
 _PUBLIC_GITHUB_URL = "https://github.com"
 _TRUE_VALUES = {"1", "true", "yes", "on"}
@@ -30,8 +32,18 @@ def no_direct_fallback_enabled() -> bool:
 
 
 def append_url_path(base_url: str, *parts: str) -> str:
-    """Join a base URL and path parts without introducing double slashes."""
-    cleaned = [part.strip("/") for part in parts if part]
+    """Join a base URL and path parts without unsafe dot segments."""
+    cleaned: list[str] = []
+    for part in parts:
+        if not part:
+            continue
+        segment = part.strip("/")
+        try:
+            validate_path_segments(segment, context="URL path part")
+        except PathTraversalError as exc:
+            raise ValueError("URL path parts must not contain dot segments") from exc
+        if segment:
+            cleaned.append(segment)
     if not cleaned:
         return base_url.rstrip("/")
     return "/".join([base_url.rstrip("/"), *cleaned])
@@ -68,7 +80,7 @@ def release_metadata_public_lookup_blocked(github_url: str | None = None) -> boo
         no_direct_fallback_enabled()
         and is_public_github_url(github_url)
         and get_release_metadata_url() is None
-        and not os.environ.get(VERSION, "").strip()
+        and not os.environ.get(VERSION_ENV_VAR, "").strip()
     )
 
 

src/apm_cli/commands/self_update.py

@@ -71,15 +71,15 @@ def _get_update_installer_suffix() -> str:
 
 
 def _get_manual_update_command() -> str:
-    """Return the manual update command for the current platform."""
+    """Return the manual update action for the current platform."""
     if _is_windows_platform():
         if get_installer_base_url() is not None:
             installer_url = "$env:APM_INSTALLER_BASE_URL/install.ps1"
         else:
             try:
                 installer_url = _get_update_installer_url()
             except RuntimeError:
-                installer_url = "$env:APM_INSTALLER_BASE_URL/install.ps1"
+                return "Set APM_INSTALLER_BASE_URL and re-run 'apm self-update'."
         return f"powershell -ExecutionPolicy Bypass -c 'irm \"{installer_url}\" | iex'"
 
     if get_installer_base_url() is not None:
@@ -88,7 +88,7 @@ def _get_manual_update_command() -> str:
         try:
             installer_url = _get_update_installer_url()
         except RuntimeError:
-            installer_url = "$APM_INSTALLER_BASE_URL/install.sh"
+            return "Set APM_INSTALLER_BASE_URL and re-run 'apm self-update'."
     return f'curl -sSL "{installer_url}" | sh'
 
 
@@ -112,7 +112,18 @@ def _get_installer_run_command(script_path: str) -> list[str]:
     return [shell_path, script_path]
 
 
-@click.command(name="self-update", help="Update the APM CLI binary itself to the latest version")
+@click.command(
+    name="self-update",
+    help=(
+        "Update the APM CLI binary itself to the latest version.\n\n"
+        "Environment variables for enterprise bootstrap mirrors:\n"
+        "  APM_RELEASE_METADATA_URL  Mirror latest.json release metadata.\n"
+        "  APM_RELEASE_BASE_URL      Mirror release assets at {base}/{tag}/{asset}.\n"
+        "  APM_INSTALLER_BASE_URL    Mirror install.sh/install.ps1 for self-update.\n"
+        "  APM_PYPI_INDEX_URL        PyPI mirror for installer pip fallback.\n"
+        "  APM_NO_DIRECT_FALLBACK    Set to 1 to fail closed on public fallback.\n"
+    ),
+)
 @click.option("--check", is_flag=True, help="Only check for updates without installing")
 def self_update(check):
     """Update APM CLI to the latest version (like npm update -g npm).
@@ -174,7 +185,7 @@ def self_update(check):
                 )
             else:
                 logger.error("Unable to fetch latest version from remote")
-                logger.progress("Please check your internet connection or try again later")
+                logger.info("Check your internet connection or try again later.")
             sys.exit(1)
 
         from ..utils.version_checker import is_newer_version
@@ -259,12 +270,12 @@ def self_update(check):
 
         except ImportError:
             logger.error("'requests' library not available")
-            logger.progress("Please update manually using:")
+            logger.info("Update manually using:")
             click.echo(f"  {_get_manual_update_command()}")
             sys.exit(1)
         except Exception as e:
             logger.error(f"Update failed: {e}")
-            logger.progress("Please update manually using:")
+            logger.info("Update manually using:")
             click.echo(f"  {_get_manual_update_command()}")
             sys.exit(1)
 

src/apm_cli/core/auth.py

@@ -192,8 +192,11 @@ def __init__(
         self,
         token_manager: GitHubTokenManager | None = None,
         logger: object | None = None,
+        *,
+        allow_external_fallback: bool = True,
     ):
         self._token_manager = token_manager or GitHubTokenManager()
+        self._allow_external_fallback = allow_external_fallback
         self._cache: dict[tuple, AuthContext] = {}
         self._lock = threading.Lock()
         # F2/F3 #852: optional logger lets the install command route the
@@ -897,6 +900,9 @@ def _resolve_token(self, host_info: HostInfo, org: str | None) -> tuple[str | No
             source = self._identify_env_source(purpose)
             return token, source, "basic"
 
+        if not self._allow_external_fallback:
+            return None, "none", "basic"
+
         # 3. gh CLI active account (eligibility gated inside the call;
         #    unsupported hosts return None instantly without a subprocess)
         gh_token = self._token_manager.resolve_credential_from_gh_cli(host_info.host)