@automattic/vip 4.1.3 → 4.1.4

package/docs/BUILD-SIGNING.md

@@ -229,7 +229,7 @@ real release with a CA certificate.
 Release builds run on **Buildkite** (Automattic's signing stack), not GitHub
 Actions. See `.buildkite/pipeline.yml` and the per-platform scripts.
 
-- **Pipeline:** `.buildkite/pipeline.yml` — three independent steps (macOS,
+- **Pipeline:** `.buildkite/pipeline.yml` — three independent binary steps (macOS,
   Windows, Linux), each building on its own native agent.
   Setup sources `.buildkite/shared-pipeline-vars` before pipeline upload
   (CI toolkit plugin pin, `BIN_BASE`, `IMAGE_ID`).
@@ -240,13 +240,151 @@ Actions. See `.buildkite/pipeline.yml` and the per-platform scripts.
   every build.
 - **macOS certs:** fastlane `match` (`fastlane/Fastfile` →
   `configure_code_signing`), `type: developer_id`, stored in S3
-  (`a8c-fastlane-match`). Signing and notarization are the
-  `sign_and_notarize` lane: Developer ID Application, identifier
-  `com.automattic.vip-cli`, no staple on a bare Mach-O.
+  (`a8c-fastlane-match`), in readonly mode. The separate
+  `configure_installer_signing` lane adds the Developer ID Installer
+  certificate through match's `additional_cert_types`. Signing and
+  notarization are the `sign_and_notarize` lane: Developer ID Application,
+  identifier `com.automattic.vip-cli`, no staple on a bare Mach-O.
 - **macOS artifacts:** per-arch `.tar.gz` of `vip-next` + `go-search-replace`,
-  both signed and notarized (online-verified).
+  both signed and notarized (online-verified), plus a signed, notarized,
+  stapled `.pkg` for each architecture.
 - **Windows / Linux artifacts:** the same tarball layout. Windows Authenticode-
-  signs both PEs via Azure Trusted Signing; Linux checksums only.
+  signs both PEs and the x64 `.msi` via Azure Trusted Signing; Linux checksums only.
+
+### Native installers
+
+Separate macOS and Windows installer jobs depend on their platform's binary
+job. They download its signed archives from the same Buildkite build, verify
+checksums and the exact two-file payload, and package those existing bytes.
+Installer jobs use Buildkite `soft_fail` so missing signing prerequisites or
+packaging failures do not fail the binary build. Their failures remain visible
+in Buildkite. Archives remain available for portable installations and
+`vip-next update`. No Node.js runtime is installed or required by these packages.
+
+| Platform            | Package                      | Installation                        |
+| ------------------- | ---------------------------- | ----------------------------------- |
+| macOS Apple Silicon | `vip-next-darwin-arm64.pkg`  | `/usr/local/lib/vip-cli/bin`        |
+| macOS Intel         | `vip-next-darwin-amd64.pkg`  | `/usr/local/lib/vip-cli/bin`        |
+| Windows x64         | `vip-next-windows-amd64.msi` | `%ProgramFiles%\Automattic\VIP CLI` |
+
+Run the package to install or upgrade; administrative privileges are required.
+Open a new terminal afterward, then run `vip-next --version`. The macOS package
+adds `/etc/paths.d/vip-cli`; Windows adds its directory to the system PATH and
+removes that entry on uninstall. Neither package creates a `vip` alias or
+replaces the Node/npm installation. Existing earlier PATH entries can still
+select a different `vip-next`; use `command -v vip-next` (macOS) or
+`where.exe vip-next` (Windows) to identify the active installation.
+
+Installer-owned directories contain `.vip-next-installer.json`. The Go updater
+recognizes this file and directs users to download the appropriate installer
+instead of replacing package-managed binaries. Keep this metadata intact.
+`vip-next update --check` still checks for available releases. Portable tarballs
+do not contain this marker and retain their existing self-update behavior.
+
+On Windows, uninstall **VIP CLI** through Installed apps or `msiexec /x` with
+the installed package. On macOS, run:
+
+```sh
+sudo /usr/local/lib/vip-cli/uninstall.sh
+```
+
+The macOS uninstaller removes only package-owned files, the matching PATH entry,
+and its receipt (`com.automattic.vip-cli`); it preserves other files in the
+installation directory. Neither uninstaller deletes user configuration or
+credentials. Uninstall first if deliberately moving to an older version.
+
+#### Build prerequisites
+
+- **macOS:** `configure_code_signing` retrieves only the **Developer ID Application**
+  certificate. The installer job separately calls `configure_installer_signing`
+  for the **Developer ID Installer** certificate. Both use the existing fastlane
+  match S3 storage in readonly mode. Builds never create or renew certificates.
+  The Installer certificate is not yet in match storage, so the installer job
+  fails until it is provisioned (see below). Xcode command-line tools provide
+  `pkgbuild`, `productbuild`, `productsign`, `notarytool`, and `stapler`.
+- **Windows:** the build uses .NET SDK 8 and pinned WiX 5.0.2, with a matching
+  UI extension, as build-only tools. WiX is restored into a temporary build
+  directory. This pin does not adopt WiX 6+ sponsorship requirements. Existing
+  Azure Trusted Signing credentials/signing tools sign the final MSI.
+- Missing signing prerequisites fail only the corresponding job; there is no
+  unsigned fallback. Binary job failures still fail the build. Installer jobs
+  upload explicitly only after all packages pass signing and payload verification;
+  automatic post-failure uploads are disabled. Checksums follow final signing/stapling.
+
+The promotion helper requires all five archive/checksum pairs (10 assets).
+The three installer/checksum pairs are optional (up to 16 assets total), but a
+package and its checksum must appear together. It verifies every supplied
+checksum, the exact two-binary tar layout, and the installer container type.
+Unknown, duplicate, incomplete, or corrupt artifacts still block promotion. Native jobs verify
+signatures; the Linux promotion job does not independently verify Apple or
+Authenticode signatures. Before checksumming/uploading, macOS expands the final
+PKG and Windows performs a temporary administrative extraction of the signed
+MSI to verify the packaged executable hashes, license, and ownership metadata.
+These checks do not install the CLI on the Buildkite host.
+
+#### Provisioning the Developer ID Installer certificate
+
+App Store Connect's API does not model this certificate type at all:
+`filter[certificateType]=DEVELOPER_ID_INSTALLER` is rejected as an invalid
+value, and the accepted list contains `DEVELOPER_ID_APPLICATION` and
+`DEVELOPER_ID_KEXT` but no installer entry. No API-driven inventory can
+therefore report whether the team already holds one; check
+<https://developer.apple.com/account/resources/certificates> directly. Creating
+one is Account Holder only and cannot be automated from CI.
+
+Import the `.cer` and `.p12` into match storage (the command prompts for both
+paths):
+
+```sh
+bundle exec fastlane match import \
+  --type developer_id_installer \
+  --platform macos \
+  --team_id PZYM8XX95Q \
+  --storage_mode s3 \
+  --s3_bucket a8c-fastlane-match \
+  --s3_region us-east-2 \
+  --skip_provisioning_profiles true \
+  --skip_certificate_matching true
+```
+
+`--skip_certificate_matching true` is required, not optional: without it
+`match import` looks the certificate up on the portal by type to recover its
+ID, which fails on the same rejected filter value.
+
+Note the asymmetry: `match import` handles `developer_id_installer` as a
+top-level `--type`, but `match` itself does not. Fetching it requires
+`additional_cert_types`, as `configure_installer_signing` does — passing it as
+match's top-level `type` silently installs an Apple Distribution certificate
+instead and reports success.
+
+#### Package version ordering
+
+MSI requires three numeric version fields. Both installer formats use
+`major.minor.(patch * 1000 + stage)` from `cmd/installer-version`: development
+builds use stage 0; alpha.N uses 100+N; beta.N uses 300+N; rc.N uses 500+N;
+stable uses 999. For example, `5.0.0-beta.1` becomes `5.0.301` and `5.0.0`
+becomes `5.0.999`. The binaries retain their full semantic version.
+
+Major/minor are limited to 255, patch to 64, and prerelease sequence to 199.
+Unsupported values fail explicitly in installer jobs; binary releases retain
+their existing semantic-version range.
+Development builds of the same semantic base share a package version and may
+require uninstalling the previous development MSI before installing another.
+
+#### Installer tests
+
+`python3 -m unittest discover -s packaging/macos -p 'test_package.py'` creates
+and expands real unsigned packages in temporary directories. It verifies
+payload bytes and runs preinstall conflict/downgrade checks against a temporary
+volume tree; it does not install on the host.
+
+The existing Go CI native matrix also runs `packaging/macos/test-install.sh`
+and `packaging/windows/test-msi.ps1` on disposable GitHub-hosted runners. These
+tests require `VIP_INSTALLER_E2E=1`, check for pre-existing installations, and
+exercise actual install, upgrade, downgrade refusal, executable versions, PATH,
+updater ownership, and uninstall using unsigned fixture packages. They are not
+run on shared Buildkite agents. Signature/notarization validation happens in
+the production Buildkite build and must also pass before a release is promoted.
 
 ### GitHub prerelease promotion setup
 
@@ -282,6 +420,9 @@ On a Buildkite build, confirm:
 - macOS binaries: `codesign --verify --strict --verbose=2` passes and
   `codesign --display` shows `Identifier=com.automattic.vip-cli`.
 - Windows: `signtool verify /pa /v <exe>` passes.
+- macOS installers: `pkgutil --check-signature <pkg>`, `xcrun stapler validate
+<pkg>`, and `spctl --assess --type install <pkg>` pass.
+- Windows installer: `signtool verify /pa /v <msi>` passes.
 - Every artifact has a matching `.sha256`.
 
 ## Release checklist

package/docs/DEBUGGING.md

@@ -31,3 +31,64 @@ For help, see: https://nodejs.org/en/docs/inspector
 6. Confirm that you attached the debugger to continue command execution.
 7. Resolve the problem.
 8. [Optional but recommended] Pay it forward and implement a similar approach to other internal/external tooling.
+
+## Go CLI diagnostics
+
+Use `-d` or `--debug` to send diagnostics to stderr while keeping command results on stdout:
+
+```sh
+vip-next dev-env list --debug
+vip-next @example.develop edge-workers list -d --format=json > workers.json
+```
+
+The Go CLI uses the corresponding Node CLI namespaces. Select namespaces with a
+comma-separated list or wildcards, and exclude namespaces with a leading `-`:
+
+```sh
+vip-next @example.develop edge-workers list --debug='@automattic/vip:http*'
+vip-next dev-env list --debug='*,-vip:proxy-dispatcher'
+DEBUG='@automattic/vip:bin:dev-environment' vip-next dev-env list
+```
+
+A nonempty debug flag overrides `DEBUG`. For remote WP-CLI, put VIP's debug flag **before**
+`wp`; arguments after `wp` belong to WP-CLI:
+
+```sh
+vip-next @example.develop -d wp option get home
+```
+
+### Available diagnostics
+
+| Namespace                                                                                  | Diagnostics                                                                                                   |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `@automattic/vip:http`                                                                     | API requests, without URL credentials or arbitrary query parameters                                           |
+| `@automattic/vip:http:graphql`                                                             | Failed requests, retries, operation names, HTTP status, safe GraphQL error metadata                           |
+| `vip:proxy-dispatcher`                                                                     | Selected proxy scheme and host                                                                                |
+| `@automattic/vip:analytics:clients:pendo`                                                  | Telemetry send/skip stages and HTTP response status, without credentials, event properties or response bodies |
+| `@automattic/vip:rechallenge:*`                                                            | Step-up session creation, pending polling, flow failures                                                      |
+| `@automattic/vip:bin:dev-environment`                                                      | Local environment lifecycle, discovered environments, container status, import and execution stages           |
+| `@automattic/vip:bin:config:envvar`                                                        | Remote and local environment-variable operations, without values                                              |
+| `@automattic/vip:bin:config-software`                                                      | Software update requests and polling                                                                          |
+| `@automattic/vip:bin:vip-app-deploy*`                                                      | Deployment validation and upload/deployment stages                                                            |
+| `@automattic/vip:bin:vip-import-sql`, `vip:vip-import-sql`, `vip:validations:line-by-line` | SQL import options and validation summaries                                                                   |
+| `vip:vip-import-media`                                                                     | Media import summaries                                                                                        |
+| `vip:lib/client-file-uploader`                                                             | Compression, checksum computation, upload strategy and completion                                             |
+| `vip:lib/site-import/status`                                                               | SQL import job and step status                                                                                |
+| `@automattic/vip:lib:search-and-replace`                                                   | Input/output routing and processing stages                                                                    |
+| `@automattic/vip:wp`, `@automattic/vip:wp/ssh`                                             | Remote connection, retry and exit stages                                                                      |
+
+Messages follow each runtime's implementation. Go uses Compose rather than Lando,
+so Lando initialization messages do not apply. Raw argument, configuration,
+response, SQL and credential dumps from older Node diagnostics are replaced with
+targeted summaries. A successful command can remain quiet when its implementation
+has no applicable diagnostics, or when its namespaces are excluded.
+
+The command-family audit covered app, backup, cache, config, db, defensive-mode,
+dev-env, edge-workers, export, import, login, logout, logs, search-replace,
+slowlogs, sync, update, whoami and wp. Families without command-specific Node
+diagnostics use shared request logging where applicable. The Go-only updater has
+no Node command diagnostics to port. Use `DEBUG` to inspect Pendo delivery during
+authentication bootstrap, before command flags are parsed. Pendo requests use the
+current stored token and are skipped when no token is available. Delivery failures
+do not fail the command. Tracking opt-outs also disable Pendo; these diagnostics
+do not add credential-store dumps.

package/docs/GO-UPDATES.md

@@ -86,6 +86,12 @@ beside the CLI. PATH and `VIP_SEARCH_REPLACE_BIN` targets are never overwritten;
 an active override continues to control helper execution.
 
 Recognized package-managed installations receive package-manager instructions
-instead of file replacement. Missing bundles, ambiguous layouts, and unwritable
+instead of file replacement. Installations created by the macOS `.pkg` or
+Windows `.msi` contain `.vip-next-installer.json` beside the binaries; keep this
+file intact. When an update is available, `vip-next update` directs these
+installations to the matching installer download. `--check` remains available.
+See [native installer installation and upgrades](BUILD-SIGNING.md#native-installers).
+
+Missing bundles, ambiguous layouts, and unwritable
 locations require manual installation. The updater does not elevate privileges.
 Supported release assets are macOS and Linux amd64/arm64, and Windows amd64.

package/docs/RELEASING.md

@@ -87,8 +87,9 @@ To publish a prerelease:
 4. The workflow creates the tag at the selected full commit and creates a draft
    release. The tag triggers Buildkite's native signing jobs.
 5. Wait while the workflow finds the Buildkite build with that exact tag and
-   commit, downloads all five archives and checksums, validates the archive
-   contents, and uploads the verified files.
+   commit, downloads all five archives, any available native installers, and their
+   checksums, validates the archive contents and installer containers, and
+   uploads the verified files. See [native installers](BUILD-SIGNING.md#native-installers).
 6. The release becomes public only after all verification and uploads succeed.
 
 If a run fails, its tag and draft release remain in place. Fix the cause and

package/docs/SETUP.md

@@ -98,7 +98,7 @@ This application uses environmental variables for vital configuration informatio
 TODO: Update description of the variables.
 
 - `API_HOST`: HTTP endpoint to use rather than the default. [For internal VIP use](TESTING.md#local-testing).
-- `DEBUG API_HOST`:
+- `DEBUG`: Enable diagnostic namespaces in the Node.js and Go CLIs, for example `DEBUG='@automattic/vip:http*'`. See [debugging](DEBUGGING.md).
 - `DOCKER_CERT_PATH`:
 - `DOCKER_CLIENT_TIMEOUT`:
 - `DOCKER_HOST`:
@@ -107,6 +107,7 @@ TODO: Update description of the variables.
 - `SOCKS_PROXY`:
 - `HTTP_PROXY`:
 - `NO_PROXY`:
+- `VIP_INSTALLER_E2E`: Set to `1` only for native installer lifecycle tests on disposable GitHub-hosted runners. The tests also require `GITHUB_ACTIONS=true` and `RUNNER_ENVIRONMENT=github-hosted`; they install and uninstall system-wide fixture packages. See [installer tests](BUILD-SIGNING.md#installer-tests).
 - `VIP_NO_UPDATE_NOTIFIER`: Set to `1` to disable automatic update checks and notices in the Go CLI. Explicit `vip-next update` commands remain available. See [Go CLI updates](GO-UPDATES.md).
 - `VIP_PROXY`: [For internal VIP use](TESTING.md#local-testing).
 - `VIP_USE_SYSTEM_PROXY`:

package/fastlane/Fastfile

@@ -9,6 +9,7 @@ PROJECT_ROOT_FOLDER = File.dirname(File.expand_path(__dir__))
 
 APPLE_TEAM_ID = 'PZYM8XX95Q'
 SIGNING_IDENTITY = "Developer ID Application: Automattic, Inc. (#{APPLE_TEAM_ID})"
+INSTALLER_SIGNING_IDENTITY = "Developer ID Installer: Automattic, Inc. (#{APPLE_TEAM_ID})"
 
 # The signature's designated requirement embeds this identifier, and the Keychain ACL
 # guarding the master key is bound to that requirement. `codesign` otherwise derives it
@@ -38,7 +39,7 @@ before_all do
   setup_ci
 end
 
-# Fetch the Developer ID Application certificate into the keychain.
+# Fetch only the Developer ID Application certificate into the keychain.
 #
 # @param readonly [Boolean] Use `true` to only fetch the existing certificate from S3 via
 #   `match`. Use `false` to create or renew it on App Store Connect.
@@ -60,6 +61,59 @@ lane :configure_code_signing do |readonly: true|
   )
 end
 
+# Fetch the Developer ID Installer certificate into the keychain.
+#
+# Separate from `configure_code_signing` so a missing Installer certificate cannot stop the
+# binary jobs publishing portable archives.
+#
+# Do not collapse this into match's top-level `type: 'developer_id_installer'`: match maps only
+# `developer_id_application` through to the certificate generator, so the installer type
+# silently resolves to an Apple Distribution certificate (`match/lib/match/generator.rb`).
+#
+# Readonly with no override, because creating this certificate needs Apple Account Holder
+# access that an App Store Connect API key does not grant. Provision it out of band with
+# `fastlane match import --type developer_id_installer`.
+#
+lane :configure_installer_signing do
+  require_env_vars!(*CODE_SIGNING_ENV_VARS)
+
+  sync_code_signing(
+    type: 'developer_id',
+    additional_cert_types: ['developer_id_installer'],
+    platform: 'macos',
+    team_id: APPLE_TEAM_ID,
+    app_identifier: [],
+    skip_provisioning_profiles: true,
+    readonly: true,
+    **CODE_SIGNING_STORAGE_OPTIONS
+  )
+
+  verify_installer_identity!
+end
+
+# The PKG has its own signing identity and stapled notarization ticket. Fetch
+# the Installer certificate via configure_installer_signing before invoking this.
+lane :sign_and_notarize_installer do |package:|
+  package = resolve_from_project_root(package)
+  UI.user_error!("No installer at '#{package}'") unless File.file?(package)
+  require_env_vars!(*ASC_API_KEY_ENV_VARS)
+  signed = "#{package}.signed.pkg"
+  begin
+    sh('productsign', '--sign', INSTALLER_SIGNING_IDENTITY, '--timestamp', package, signed)
+    details = sh('pkgutil', '--check-signature', signed, log: false)
+    unless details.include?(INSTALLER_SIGNING_IDENTITY)
+      UI.user_error!("Installer is not signed by '#{INSTALLER_SIGNING_IDENTITY}'")
+    end
+    notarize(package: signed, skip_stapling: true, api_key: app_store_connect_api_key, print_log: true)
+    sh('xcrun', 'stapler', 'staple', signed)
+    sh('xcrun', 'stapler', 'validate', signed)
+    sh('spctl', '--assess', '--type', 'install', '--verbose=2', signed)
+    FileUtils.mv(signed, package)
+  ensure
+    FileUtils.rm_f(signed)
+  end
+end
+
 # Sign a built CLI binary with the Developer ID certificate and submit it for notarization.
 #
 # Run `configure_code_signing` first, or run this on a machine that already holds the
@@ -92,8 +146,8 @@ lane :sign_and_notarize do |binary:|
 
   notarize(
     package: archive,
-    # Only bundles and disk images can carry a stapled ticket. A bare binary relies on
-    # the online Gatekeeper check.
+    # A bare binary cannot carry a stapled ticket and relies on the online
+    # Gatekeeper check. The separate PKG lane staples the installer instead.
     skip_stapling: true,
     api_key: app_store_connect_api_key,
     print_log: true
@@ -135,6 +189,15 @@ def resolve_from_project_root(path)
   File.absolute_path(path, PROJECT_ROOT_FOLDER)
 end
 
+# `match` reports success for whatever certificate storage happens to hold, so the identity
+# `productsign` needs is verified rather than assumed.
+def verify_installer_identity!
+  identities = sh('security', 'find-identity', '-v', log: false)
+  return if identities.include?(INSTALLER_SIGNING_IDENTITY)
+
+  UI.user_error!("No '#{INSTALLER_SIGNING_IDENTITY}' identity in the keychain:\n#{identities}")
+end
+
 def require_env_vars!(*names)
   missing = names.select { |name| ENV[name].to_s.empty? }
   UI.user_error!("Missing required environment variable(s): #{missing.join(', ')}") unless missing.empty?

package/fastlane/test_signing.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+
+# Evaluate the actual Fastfile DSL without accessing credentials or Apple/S3.
+module FastlaneCore
+  module Helper
+    def self.bundler?
+      true
+    end
+  end
+end
+
+module UI
+  def self.user_error!(message)
+    raise message
+  end
+end
+
+class SigningConfigurationTest < Minitest::Test
+  def setup
+    @lanes = {}
+    @calls = []
+    @dsl = Object.new
+    lanes = @lanes
+    calls = @calls
+    @dsl.define_singleton_method(:before_all) { |&block| }
+    @dsl.define_singleton_method(:lane) { |name, &block| lanes[name] = block }
+    @dsl.define_singleton_method(:sync_code_signing) do |**options|
+      calls << options
+      raise 'Installer certificate unavailable' if options[:type] == 'developer_id_installer' || options[:additional_cert_types]
+    end
+    @dsl.instance_eval(File.read(File.join(__dir__, 'Fastfile')), File.join(__dir__, 'Fastfile'))
+    @dsl.define_singleton_method(:require_env_vars!) { |*names| }
+  end
+
+  def test_missing_installer_identity_does_not_affect_application_lane
+    @lanes.fetch(:configure_code_signing).call
+    assert_equal 'developer_id', @calls.last[:type]
+    assert_equal true, @calls.last[:readonly]
+    assert_nil @calls.last[:additional_cert_types]
+    error = assert_raises(RuntimeError) { @lanes.fetch(:configure_installer_signing).call }
+    assert_equal 'Installer certificate unavailable', error.message
+    assert_equal true, @calls.last[:readonly]
+    assert_equal true, @calls.last[:skip_provisioning_profiles]
+    @lanes.fetch(:configure_code_signing).call
+  end
+
+  # Match's top-level `developer_id_installer` type silently resolves to an Apple Distribution
+  # certificate, so the supported route is pinned rather than left to preference.
+  def test_installer_lane_requests_the_installer_certificate_as_an_additional_type
+    assert_raises(RuntimeError) { @lanes.fetch(:configure_installer_signing).call }
+
+    assert_equal 'developer_id', @calls.last[:type]
+    assert_equal ['developer_id_installer'], @calls.last[:additional_cert_types]
+  end
+
+  def test_installer_lane_never_creates_certificates
+    assert_raises(RuntimeError) { @lanes.fetch(:configure_installer_signing).call }
+
+    assert_equal true, @calls.last[:readonly]
+    assert_nil @calls.last[:api_key]
+  end
+
+  def test_identity_check_accepts_the_installer_identity
+    stub_identities('  1) ABC123 "Developer ID Installer: Automattic, Inc. (PZYM8XX95Q)"')
+
+    @dsl.send(:verify_installer_identity!)
+  end
+
+  def test_identity_check_rejects_a_substituted_certificate
+    stub_identities('  1) ABC123 "Apple Distribution: Automattic, Inc. (PZYM8XX95Q)"')
+
+    error = assert_raises(RuntimeError) { @dsl.send(:verify_installer_identity!) }
+    assert_includes error.message, 'Developer ID Installer: Automattic, Inc. (PZYM8XX95Q)'
+  end
+
+  private
+
+  def stub_identities(output)
+    @dsl.define_singleton_method(:sh) { |*_args, **_options| output }
+  end
+end

package/internal/auth/logout.go

@@ -5,6 +5,7 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/httpproxy"
 )
 
@@ -13,13 +14,25 @@ import (
 // ignored; only a transport failure returns a non-nil error. The caller always
 // purges the local token regardless.
 func PostLogout(apiHost, rawToken string) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	return PostLogoutContext(context.Background(), apiHost, rawToken)
+}
+
+// PostLogoutContext preserves invocation diagnostics and cancellation while
+// retaining the bounded, best-effort server-side invalidation behavior.
+func PostLogoutContext(ctx context.Context, apiHost, rawToken string) error {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
 	defer cancel()
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiHost+"/logout", nil)
 	if err != nil {
 		return err
 	}
 	req.Header.Set("Authorization", "Bearer "+rawToken)
+	// Node's HTTP helper logs the request target. Only expose the fixed logout
+	// path and target host; URL userinfo, queries and headers may carry secrets.
+	debuglog.Printf(ctx, "@automattic/vip:http", "running fetch %s://%s/logout", req.URL.Scheme, req.URL.Host)
 	// NOT http.DefaultClient: this request carries the bearer token, and Node
 	// routes /logout through api/http.ts's proxy agent. See internal/httpproxy.
 	resp, err := httpproxy.Client().Do(req)

package/internal/auth/logout_test.go

@@ -1,9 +1,14 @@
 package auth
 
 import (
+	"bytes"
+	"context"
 	"net/http"
 	"net/http/httptest"
+	"strings"
 	"testing"
+
+	"github.com/Automattic/vip/internal/debuglog"
 )
 
 func TestPostLogoutSendsBearer(t *testing.T) {
@@ -21,6 +26,47 @@ func TestPostLogoutSendsBearer(t *testing.T) {
 	}
 }
 
+func TestPostLogoutContextDiagnostics(t *testing.T) {
+	for _, key := range []string{"VIP_PROXY", "vip_proxy", "SOCKS_PROXY", "socks_proxy", "NO_PROXY", "no_proxy"} {
+		t.Setenv(key, "")
+	}
+	proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost || r.URL.Path != "/logout" || r.Header.Get("Authorization") != "Bearer fixture-token-secret" {
+			t.Error("logout request changed")
+		}
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte("server-body-secret"))
+	}))
+	defer proxy.Close()
+	t.Setenv("VIP_USE_SYSTEM_PROXY", "1")
+	t.Setenv("HTTPS_PROXY", strings.Replace(proxy.URL, "http://", "http://proxy-user:proxy-password-secret@", 1))
+	for _, namespaces := range []string{"", "@automattic/vip:http,vip:proxy-dispatcher"} {
+		t.Run(namespaces, func(t *testing.T) {
+			var out bytes.Buffer
+			ctx := debuglog.WithLogger(context.Background(), namespaces, &out)
+			if err := PostLogoutContext(ctx, "http://url-user:url-password-secret@logout.example.test", "fixture-token-secret"); err != nil {
+				t.Fatal(err)
+			}
+			if namespaces == "" {
+				if out.Len() != 0 {
+					t.Fatalf("default diagnostics = %q", out.String())
+				}
+				return
+			}
+			for _, want := range []string{"@automattic/vip:http running fetch http://logout.example.test/logout", "vip:proxy-dispatcher Enabling fetch dispatcher proxy support using config: " + proxy.URL} {
+				if !strings.Contains(out.String(), want) {
+					t.Errorf("missing %q in %q", want, out.String())
+				}
+			}
+			for _, forbidden := range []string{"secret", "proxy-user", "url-user", "Authorization"} {
+				if strings.Contains(out.String(), forbidden) {
+					t.Errorf("diagnostics exposed %q: %q", forbidden, out.String())
+				}
+			}
+		})
+	}
+}
+
 func TestPostLogoutIgnoresServerError(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.WriteHeader(http.StatusInternalServerError)

package/internal/debuglog/debuglog.go

@@ -0,0 +1,85 @@
+// Package debuglog emits opt-in diagnostics using Node debug namespace selectors.
+// Loggers belong to an invocation context, so commands and tests cannot leak
+// their debug settings or output writers into another invocation.
+package debuglog
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+	"sync"
+	"unicode"
+)
+
+type contextKey struct{}
+
+type logger struct {
+	mu               sync.Mutex
+	out              io.Writer
+	include, exclude []*regexp.Regexp
+}
+
+// WithLogger accepts comma/whitespace-separated namespaces, '*' wildcards,
+// and '-' exclusions, matching the Node debug package's selector grammar.
+func WithLogger(ctx context.Context, namespaces string, out io.Writer) context.Context {
+	l := &logger{out: out}
+	for _, pattern := range strings.FieldsFunc(namespaces, func(r rune) bool { return r == ',' || unicode.IsSpace(r) }) {
+		exclude := strings.HasPrefix(pattern, "-")
+		pattern = strings.TrimPrefix(pattern, "-")
+		if pattern == "" {
+			continue
+		}
+		expression := "^" + strings.ReplaceAll(regexp.QuoteMeta(pattern), `\*`, ".*") + "$"
+		re := regexp.MustCompile(expression)
+		if exclude {
+			l.exclude = append(l.exclude, re)
+		} else {
+			l.include = append(l.include, re)
+		}
+	}
+	return context.WithValue(ctx, contextKey{}, l)
+}
+
+// Enabled lets callers avoid constructing expensive diagnostic metadata when
+// its namespace is disabled.
+func Enabled(ctx context.Context, namespace string) bool {
+	if ctx == nil {
+		return false
+	}
+	l, _ := ctx.Value(contextKey{}).(*logger)
+	if l == nil || l.out == nil {
+		return false
+	}
+	for _, re := range l.exclude {
+		if re.MatchString(namespace) {
+			return false
+		}
+	}
+	for _, re := range l.include {
+		if re.MatchString(namespace) {
+			return true
+		}
+	}
+	return false
+}
+
+// Printf writes one diagnostic line if namespace is enabled. Callers must pass
+// only safe fields: this function escapes terminal controls, not secrets.
+func Printf(ctx context.Context, namespace, format string, args ...any) {
+	if !Enabled(ctx, namespace) {
+		return
+	}
+	l := ctx.Value(contextKey{}).(*logger)
+	line := namespace + " " + fmt.Sprintf(format, args...)
+	line = strings.Map(func(r rune) rune {
+		if unicode.IsControl(r) {
+			return ' '
+		}
+		return r
+	}, line)
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	_, _ = fmt.Fprintln(l.out, line)
+}