feat(distribution): add enterprise bootstrap mirrors (#1733)

* feat(distribution): add enterprise bootstrap mirrors

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

* Redact bootstrap mirror output

Folds copilot-pull-request-reviewer follow-ups (credential redaction in mirror output, copy-pasteable self-update fallback, changelog placement).

Refs #1680

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

* fix(install): do not send GitHub token to mirror hosts

install.sh attached the resolved GitHub token to APM_RELEASE_METADATA_URL
and APM_RELEASE_BASE_URL mirror requests, and install.ps1 leaked it on the
asset final-fallback and checksum-retry paths. Gate every auth attach on
mirror-env absence so the token rides only to the canonical GitHub /
configured GHES host, never to an operator mirror. The two scripts are now
symmetric. Adds static symmetry traps plus executable fail-closed exit-code
tests (no network) for the installer guards.

addresses CEO follow-up #1 (Auth Expert / Supply Chain) and Test Coverage
follow-up #3 on PR #1733.

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

* docs(install): clarify fail-closed GHES boundary and pip egress

Document that APM_NO_DIRECT_FALLBACK keys off the public github.com default:
a custom GHES GITHUB_URL still egresses to that host, so 'no direct fallback'
means no public fallback, not zero egress. Extend the no-egress smoke recipe
to wrap pip alongside curl so the PyPI fallback path is actually proven, and
note the token-to-canonical-host-only rule across installer and self-update
docs and the apm-guide usage doc.

addresses CEO follow-up #2 (Supply Chain), #4 (smoke pip path), and Doc
Writer nit on PR #1733.

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

* refactor(version-checker): use relative bootstrap_mirror import

Align version_checker.py with self_update.py: import the shared
bootstrap_mirror module via a package-relative path (from ..bootstrap_mirror)
for one consistent convention across both consumers.

addresses Python Architect nit on PR #1733.

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

* fix: avoid auth header on release metadata mirrors

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

---------

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

Author: danielmeppiel

CHANGELOG.md

@@ -17,6 +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)
 
 ### Fixed
 

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

@@ -90,14 +90,113 @@ jobs:
 |----------|---------|-------------|
 | `APM_INSTALL_DIR` | `/usr/local/bin` (Unix) / `%LOCALAPPDATA%\Programs\apm\bin` (Windows) | Directory for the `apm` symlink / `apm.cmd` shim |
 | `APM_LIB_DIR` | `$(dirname APM_INSTALL_DIR)/lib/apm` | *(Unix only)* Directory for the full binary bundle. Must end with `/apm` (for example, `/lib/apm`). The installer rejects shared directories (e.g. `$HOME/.local/share`) to prevent accidental data loss. |
-| `GITHUB_URL` | `https://github.com` | Base GitHub URL (asset downloads **and** API host: `api.github.com` on github.com, `{GITHUB_URL}/api/v3` on GHES). Must be `https://`. |
+| `GITHUB_URL` | `https://github.com` | Base GitHub URL (asset downloads **and** API host: `api.github.com` on github.com, `{GITHUB_URL}/api/v3` on GHES). Must be `https://` on Windows. |
 | `APM_REPO` | `microsoft/apm` | Repository as `owner/name` |
 | `VERSION` | *(latest)* | Pin a release tag (skips the **releases/latest** HTTP API). Must look like `v1.2.3` or `1.2.3`. |
+| `APM_RELEASE_METADATA_URL` | *(unset)* | Exact mirror URL for release metadata, usually `latest.json` with at least `{"tag_name":"vX.Y.Z"}`. |
+| `APM_RELEASE_BASE_URL` | *(unset)* | Base URL for release assets laid out as `{base}/{tag}/{asset}` and `{base}/{tag}/{asset}.sha256`. |
+| `APM_INSTALLER_BASE_URL` | *(unset)* | Base URL containing `install.sh` and `install.ps1`; used by `apm self-update` and by your bootstrap one-liner. |
+| `APM_PYPI_INDEX_URL` | *(unset)* | PyPI-compatible mirror used when the installer falls back to pip. |
+| `APM_NO_DIRECT_FALLBACK` | *(unset)* | Set to `1` to fail closed when a mirror is missing or unreachable instead of using public GitHub, `aka.ms`, or PyPI. |
 | `APM_SKIP_CHECKSUM` | *(unset)* | Windows only: set to `1` to skip `.sha256` verification on **pinned** installs (emergency only). |
 
-> **Note - Unix (`install.sh`):** Latest-release discovery still calls `https://api.github.com/repos/.../releases/latest` unless `VERSION` is set. For GHES or mirrors with no access to `api.github.com`, pin `VERSION` so the script never hits that endpoint.
->
-> **Note - Windows (`install.ps1`):** The **releases/latest** URL is derived from `GITHUB_URL`: `https://api.github.com` for GitHub.com, or `{GITHUB_URL}/api/v3` for GitHub Enterprise Server. Air-gapped runners should still set `VERSION` so the installer does not need the API at all. When `VERSION` is pinned, the release **`.sha256`** file is required unless you set **`APM_SKIP_CHECKSUM=1`** (emergency only).
+### Enterprise bootstrap mirror mode
+
+Mirror mode lets locked-down workstations install and update APM without direct public egress:
+
+```bash
+export APM_INSTALLER_BASE_URL="https://artifactory.mycorp.example/generic/apm-install"
+export APM_RELEASE_METADATA_URL="https://artifactory.mycorp.example/generic/apm-releases/latest.json"
+export APM_RELEASE_BASE_URL="https://artifactory.mycorp.example/generic/apm-releases"
+export APM_PYPI_INDEX_URL="https://artifactory.mycorp.example/api/pypi/python-proxy/simple"
+export APM_NO_DIRECT_FALLBACK=1
+
+curl -sSL "$APM_INSTALLER_BASE_URL/install.sh" | sh
+apm self-update --check
+```
+
+For Windows:
+
+```powershell
+$env:APM_INSTALLER_BASE_URL = "https://artifactory.mycorp.example/generic/apm-install"
+$env:APM_RELEASE_METADATA_URL = "https://artifactory.mycorp.example/generic/apm-releases/latest.json"
+$env:APM_RELEASE_BASE_URL = "https://artifactory.mycorp.example/generic/apm-releases"
+$env:APM_PYPI_INDEX_URL = "https://artifactory.mycorp.example/api/pypi/python-proxy/simple"
+$env:APM_NO_DIRECT_FALLBACK = "1"
+
+irm "$env:APM_INSTALLER_BASE_URL/install.ps1" | iex
+apm self-update --check
+```
+
+Mirror layout for binary releases:
+
+```text
+apm-releases/
+  latest.json
+  v0.19.0/
+    apm-linux-x86_64.tar.gz
+    apm-darwin-arm64.tar.gz
+    apm-windows-x86_64.zip
+    apm-windows-x86_64.zip.sha256
+```
+
+`APM_NO_DIRECT_FALLBACK=1` makes missing mirror settings and unreachable mirrors hard failures. It does not replace package-install proxying; keep using `PROXY_REGISTRY_URL` and `PROXY_REGISTRY_ONLY=1` for `apm install` dependencies.
+
+#### 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.
+
+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.
+
+### No-egress smoke test
+
+Run this on a disposable Linux or macOS runner. It starts a local mirror, wraps both `curl` and `pip` with deny-lists for public hosts, and expects the installer to fail only after downloading the fake archive. Any request to GitHub, `aka.ms`, PyPI, Homebrew, or Scoop fails the smoke test immediately. The `pip` wrapper makes the PyPI egress path explicit: pip fallback is gated by `APM_NO_DIRECT_FALLBACK` + `APM_PYPI_INDEX_URL`, so the wrapper proves pip cannot reach public PyPI even if the binary path falls back to it.
+
+```bash
+set -eu
+rm -rf .apm-mirror-smoke
+mkdir -p .apm-mirror-smoke/mirror/apm-install \
+  .apm-mirror-smoke/mirror/apm-releases/v9.9.9 \
+  .apm-mirror-smoke/bin
+cp install.sh .apm-mirror-smoke/mirror/apm-install/install.sh
+printf '{"tag_name":"v9.9.9"}\n' > .apm-mirror-smoke/mirror/apm-releases/latest.json
+printf 'not-a-real-archive\n' > .apm-mirror-smoke/mirror/apm-releases/v9.9.9/apm-linux-x86_64.tar.gz
+cat > .apm-mirror-smoke/bin/curl <<'SH'
+#!/bin/sh
+case " $* " in
+  *github.com*|*api.github.com*|*aka.ms*|*pypi.org*|*pythonhosted.org*|*brew.sh*|*scoop*)
+    echo "public egress blocked: $*" >&2
+    exit 70
+    ;;
+esac
+exec /usr/bin/curl "$@"
+SH
+cat > .apm-mirror-smoke/bin/pip <<'SH'
+#!/bin/sh
+# Deny public PyPI; allow only the configured mirror index.
+case " $* " in
+  *pypi.org*|*pythonhosted.org*)
+    echo "public pip egress blocked: $*" >&2
+    exit 70
+    ;;
+esac
+exec /usr/bin/pip "$@"
+SH
+cp .apm-mirror-smoke/bin/pip .apm-mirror-smoke/bin/pip3
+chmod +x .apm-mirror-smoke/bin/curl .apm-mirror-smoke/bin/pip .apm-mirror-smoke/bin/pip3
+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
+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
+```
+
+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.
 
 ## Package managers
 

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

@@ -33,27 +33,38 @@ The command compares the installed version against the latest GitHub release and
 Some package-manager distributions (for example, Homebrew) disable self-update at build time. In those builds, `apm self-update` prints a distributor-defined message (such as `brew upgrade apm`) and exits without running the installer. The startup update notification is also suppressed in those builds.
 :::
 
-## Air-gapped and GitHub Enterprise environments
+## Enterprise bootstrap mirrors
 
-`apm self-update` respects the same environment variables that `install.sh` honours
-for air-gapped networks and GitHub Enterprise Server (GHE):
+`apm self-update` uses the same mirror contract as the installer scripts. These variables are additive to the older `GITHUB_URL` / `APM_REPO` / `VERSION` flow:
 
 | Variable | Default | Effect |
 |----------|---------|--------|
-| `GITHUB_URL` | `https://github.com` | Base URL of the GitHub host. When set to a GHE host (e.g. `https://gh.corp.com`), the version-check API uses `{GITHUB_URL}/api/v3` and the installer script is fetched from `{GITHUB_URL}/{APM_REPO}/raw/main/install.sh` (Unix) or `install.ps1` (Windows). |
-| `APM_REPO` | `microsoft/apm` | Repository in `owner/repo` form. Overrides the default when using a fork or an internal mirror. |
-| `VERSION` | _(unset)_ | Pin a specific release (e.g. `v1.2.3`). Skips the GitHub API call entirely -- required for fully offline setups. The pinned version is passed through to the installer subprocess. |
+| `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_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. |
+| `APM_REPO` | `microsoft/apm` | Repository in `owner/repo` form for GitHub/GHES paths. |
+| `VERSION` | _(unset)_ | Pin a release tag and skip release metadata lookup. |
 
-Examples:
+Example:
 
 ```bash
-# Air-gapped update: skip API, fetch installer from internal mirror
-GITHUB_URL=https://gh.corp.com APM_REPO=corp/apm VERSION=v1.2.3 apm self-update
+export APM_RELEASE_METADATA_URL="https://artifactory.mycorp.example/generic/apm-releases/latest.json"
+export APM_INSTALLER_BASE_URL="https://artifactory.mycorp.example/generic/apm-install"
+export APM_RELEASE_BASE_URL="https://artifactory.mycorp.example/generic/apm-releases"
+export APM_PYPI_INDEX_URL="https://artifactory.mycorp.example/api/pypi/python-proxy/simple"
+export APM_NO_DIRECT_FALLBACK=1
 
-# GHE host with version check (no VERSION pin -- API is queried via /api/v3)
-GITHUB_URL=https://gh.corp.com APM_REPO=corp/apm apm self-update --check
+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.
+
 ## Options
 
 | Flag | Description |
@@ -104,7 +115,7 @@ The installer scripts accept a version pin via environment variable -- see [Quic
 
 ## Failure modes
 
-If GitHub is unreachable, the download fails, or the installer exits non-zero, `apm self-update` exits with code `1` and prints the manual update command. Your existing binary is unaffected.
+If GitHub or a configured mirror is unreachable, the download fails, or the installer exits non-zero, `apm self-update` exits with code `1` and prints the next mirror or manual update action. Your existing binary is unaffected.
 
 ## Startup update notification