@automattic/vip 4.1.5 → 4.1.8

package/docs/SETUP.md

@@ -1,154 +0,0 @@
-# Setup
-
-## Language & requirements
-
-- Implemented in JavaScript and TypeScript.
-- Requirements are:
-  - Node, see version in [package.json](https://github.com/Automattic/vip-cli/blob/trunk/package.json)
-  - A number of NPM packages are needed, those are listed in the same file.
-  - No special hardware requirements.
-  - Network access.
-
-## Installation & setup instructions
-
-### Installation for end-users
-
-First, install the package:
-
-```bash
-npm install -g @automattic/vip
-```
-
-Then, launch the command and follow the prompts:
-
-```bash
-vip
-```
-
-If you need more information, check out our [VIP-CLI documentation](https://docs.wpvip.com/vip-cli/).
-
-### Installation for developers
-
-The section below is intended for developers.
-
-<summary><details>
-
-#### Version manager
-
-We recommend to use a version manager like [nvm](https://github.com/nvm-sh/nvm) or [nodenv](https://github.com/nodenv/nodenv) to automatically configure the version of Node required by this software package. The [.nvmrc](https://github.com/Automattic/vip-cli/blob/trunk/.nvmrc) file gives these tools the necessary hints for what version to use.
-
-#### Install and setup of API
-
-This software relies on an [API offered by WPVIP](ARCHITECTURE.md#communicating-with-wpvip-api). You may need to have a local instance of that set up for [local testing](TESTING.md#local-testing). Follow internal instructions to set it up locally.
-
-#### Fetching & installing
-
-This will fetch the package and install all dependencies:
-
-```bash
-git clone git@github.com:Automattic/vip-cli.git && \
-cd vip-cli && npm install
-```
-
-#### Building
-
-This will build all TypeScript files so they can be executed:
-
-```bash
-cd vip-cli && \
-npm run build
-```
-
-</details></summary>
-
-## Usage
-
-The software runs as standalone CLI and relies on environmental variables for configuration and a few configuration files.
-
-### Starting up locally
-
-To start the software locally, run:
-
-```bash
-vip
-```
-
-If you need more information, check out our [VIP-CLI documentation](https://docs.wpvip.com/vip-cli/).
-
-### Analytics
-
-By default, we record information about the usage of this tool using an in-house analytics sytem. If you would prefer to opt-out of this data collection, you can do so via the `DO_NOT_TRACK` environment variable. You may either export it in your shell configuration or specify it on the command line (e.g. `DO_NOT_TRACK=1 vip app list`).
-
-### Local application
-
-#### Configuring access token
-
-Install the software locally, run and follow the instructions to configure the access token.
-
-### Environmental variables
-
-#### Configuring environmental variables
-
-Environmental variables are configured in the shell. Use normal shell commands to set them.
-
-#### List of environmental variables
-
-This application uses environmental variables for vital configuration information. Find a partial list below.
-
-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`: 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`:
-- `DOCKER_TLS_VERIFY`:
-- `DO_NOT_TRACK`: [To disable tracking](SETUP.md#analytics).
-- `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`:
-- `WPVIP_DEPLOY_TOKEN`: For use with `vip app deploy` on sites that have custom deploys enabled.
-
-### Configuration files
-
-TODO: List main configuration files and their purpose. How to update.
-
-## Updating dependencies
-
-### NPM packages
-
-Dependencies generally should be updated by merging [pull requests from dependabot](https://github.com/Automattic/vip-cli/pulls/app%2Fdependabot). However, great care should be taken before merging as updating dependencies can cause fatal errors with the `vip-cli` application, or make it unstable or misbehave. There can also be effects to the release process. This can happen silently.
-
-### Upgrading Node Version
-
-To upgrade Node, follow these steps:
-
-1. Update [.nvmrc](https://github.com/Automattic/vip-cli/blob/trunk/.nvmrc) to the new version and open a pull request.
-1. Use the same pull request to update `engines.node` in [package.json](https://github.com/Automattic/vip-cli/blob/trunk/package.json).
-1. Address any test failures.
-1. Update the Node.js version locally and test before merging into the repository.
-
-Upgrading Node should be considered high-risk.
-
-### Before merging
-
-Consider removing the dependency, if it is an NPM package. Can the functionality needed from the dependency be implemented directly into `vip-cli` or our own common libraries? If not, evaluate the following:
-
-1. If the dependency is one of the [development dependencies](https://github.com/Automattic/vip-cli/blob/trunk/package.json) (`devDependencies`), and/or only used by one of those, the likelihood of customer-impacting failure is low.
-1. Is the package used in the [release process](RELEASING.md#releasing-a-new-version)? If it is, evaluate if any failure is likely to be silent. If that seems not to be the case, the risk of customer-impacting failure is low.
-
-#### Low risk dependencies
-
-If the risk of merging is low, you can go a head and merge without doing anything further (given that all tests succeed).
-
-#### Higher risk dependencies
-
-For higher risk dependencies, the routes/utilities using the dependency [will have to be tested locally](TESTING.md) and the results verified. If the main application is using the dependency, you will have to [launch it locally](SETUP.md#starting-up-locally) and verify that it runs normally.
-
-### After merging
-
-No special considerations.

package/docs/TESTING.md

@@ -1,67 +0,0 @@
-# Testing
-
-Testing is an integral part of creating new features and maintaining the software.
-
-## Automated testing
-
-A [few actions](https://github.com/Automattic/vip-cli/blob/trunk/.github/workflows/) are automatically run via Github Actions when a pull request is created or updated.
-
-### Linting
-
-We [run](https://github.com/Automattic/vip-cli/blob/trunk/.github/workflows/ci.yml) the following checks:
-
-- linting
-- format checking
-- type checks
-
-### Dependency checks
-
-We [use](https://github.com/Automattic/vip-cli/blob/trunk/.github/workflows/ci.yml) the [dependaban action](https://github.com/Automattic/vip-actions/tree/trunk/dependaban) from [Automattic/vip-actions](https://github.com/Automattic/vip-actions/) to verify that no dependencies have install scripts.
-
-### Unit tests
-
-Unit tests in [\_\_tests\_\_](https://github.com/Automattic/vip-cli/tree/trunk/__tests__) are [run](https://github.com/Automattic/vip-cli/blob/trunk/.github/workflows/ci.yml). They are powered by [Jest](https://facebook.github.io/jest/) and report any failures, along with test coverage.
-
-#### Adding new unit tests
-
-Tests should be written for any major features or security sensitive functionality, as a minimum. Writing tests for new or updated [utility functions](https://github.com/Automattic/vip-cli/blob/trunk/src/lib/utils.ts) is recommended.
-
-### E2E tests
-
-E2E test are [run](https://github.com/Automattic/vip-cli/blob/trunk/.github/workflows/devenv-e2e.yml). They can be found at [\_\_tests\_\_/devenv-e2e](https://github.com/Automattic/vip-cli/tree/trunk/__tests__/devenv-e2e).
-
-### Windows tests
-
-We run the above unit and E2E tests [on Windows as well](https://github.com/Automattic/vip-cli/blob/trunk/.github./workflows/windows-tests.yml).
-
-### CodeQL analysis
-
-CodeQL analysis is [started automatically](https://github.com/Automattic/vip-cli/blob/trunk/.github/workflows/codeql-analysis.yml).
-
-## Manual testing
-
-### Running unit tests locally
-
-[Install and set up the environment](SETUP.md#installation--setup-instructions), and then run:
-
-```bash
-npm run test
-```
-
-### Local testing
-
-To test against a local instance of the WPVIP API, you can use the `API_HOST` environment variable. Unset the `VIP_PROXY` variable as well.
-
-Examples:
-
-```bash
-VIP_PROXY="" API_HOST=http://localhost:4000 node ./dist/bin/vip
-
-VIP_PROXY="" API_HOST=http://localhost:4000 node ./dist/bin/vip app
-
-VIP_PROXY="" API_HOST=http://localhost:4000 node ./dist/bin/vip -- wp option get home
-```
-
-## Final testing before releasing
-
-TODO: How should final testing before releasing be done?

package/docs/decisions/0001-operation-scoped-elevated-token-reuse.md

@@ -1,87 +0,0 @@
----
-status: accepted
-date: 2026-07-01
----
-
-# Accept Operation-Scoped Elevated Token Reuse
-
-## Context and Problem Statement
-
-Step-up rechallenge currently issues elevated tokens scoped by GraphQL `requestedOperation` (mutation field name or operation domain), not by app, environment, or payload details.
-
-The team must decide whether this behavior should be treated as a defect that requires per-resource rebinding, or as intended product behavior.
-
-Primary workflow motivation: users may need to perform the same protected operation repeatedly across many targets, such as adding many domains to multiple environments. Requiring a new rechallenge for every target would add significant friction.
-
-## Decision Drivers
-
-- Reduce repeated operator friction in bulk workflows.
-- Preserve baseline authorization enforcement at resolver level.
-- Keep step-up semantics understandable: user confirms an operation class, not one specific payload.
-- Avoid unnecessary complexity in token minting, validation, and client caching.
-- Keep room for future hardening if product intent changes.
-
-## Considered Options
-
-- Option 1: Keep operation-scoped elevated token reuse.
-- Option 2: Require per-resource scoped elevated tokens (bind to app/environment/payload).
-- Option 3: Disable reuse and force fresh rechallenge on every protected mutation.
-
-## Decision Outcome
-
-Chosen option: Option 1, keep operation-scoped elevated token reuse.
-
-Accepted behavior: a valid elevated token for a protected operation may be reused across app/environment targets while token validity holds.
-
-This is intentional because it removes repeated rechallenge prompts in high-volume administrative workflows, including adding many domains across multiple environments.
-
-### Consequences
-
-Good, because:
-
-- Bulk operations become materially faster and less error-prone for users.
-- Behavior aligns with current implementation and avoids disruptive contract changes.
-- Security posture remains layered: resolver authorization still enforces target access for the authenticated user.
-
-Bad, because:
-
-- Some readers may incorrectly assume step-up approval is resource-bound.
-- If future product intent requires per-resource confirmation, this decision will need to be superseded and implementation changed.
-
-Neutral, because:
-
-- This decision does not change which mutations are protected; it defines scope behavior once a mutation is protected.
-
-### Confirmation
-
-The decision is considered correctly implemented when all of the following hold:
-
-- Rechallenge token scope is derived from `requestedOperation`.
-- Elevated token validation checks operation/operationDomain compatibility.
-- Resolver-level authorization remains enforced independently of elevated token scope.
-- Documentation and support guidance describe operation-scoped reuse as intended behavior.
-
-## Pros and Cons of the Options
-
-### Option 1: Keep operation-scoped elevated token reuse
-
-- Good, because it optimizes repeated protected actions across many targets.
-- Good, because it matches existing VIP CLI and GOOP behavior.
-- Bad, because it may be perceived as broader than least-privilege if readers expect resource scoping.
-
-### Option 2: Require per-resource scoped elevated tokens
-
-- Good, because it enforces tighter binding between step-up and target resource.
-- Bad, because it increases user friction and rechallenge frequency in bulk workflows.
-- Bad, because it introduces higher implementation and rollout complexity.
-
-### Option 3: Disable reuse and force fresh rechallenge every time
-
-- Good, because the model is simple and strict.
-- Bad, because it has the worst user experience for repetitive operations.
-- Bad, because it provides limited practical security gain beyond existing authorization checks.
-
-## More Information
-
-- Source validation and rationale: https://github.com/Automattic/vip-cli/pull/2869
-- Revisit trigger: if product/security policy explicitly requires per-resource step-up approval, supersede this ADR with a new decision and migration plan.

package/docs/dev-env-windows-wsl-testing.md

@@ -1,191 +0,0 @@
-# Testing `vip dev-env` on Windows & WSL (offline-domains feature)
-
-A runbook for building `vip-next` and exercising the offline managed-hosts /
-cross-platform elevation feature on a Windows machine — natively and from WSL.
-
-## TL;DR: you do NOT need to sign the binary
-
-There are two unrelated "signing" ideas; don't conflate them:
-
-1. **Authenticode code-signing the `.exe`** (`signtool`, Developer cert, SmartScreen).
-   This is **only for distribution**. A binary you build yourself and run from your
-   own terminal does **not** need it. It carries no "mark-of-the-web", so Windows
-   SmartScreen won't block it. If anything ever warns, "More info → Run anyway".
-   **For testing this feature, skip signing entirely.**
-
-2. **The local dev CA** ("WPVIP Local CA") — a self-signed certificate the dev-env
-   _generates and trusts automatically_ so HTTPS to `*.vipdev.site` is trusted by
-   your browser. **You don't do this by hand.** When you run `dev-env start`, the
-   CLI adds that CA to the Windows **Root** store and writes the hosts file — both
-   under **one UAC prompt** (`certutil -addstore Root` + the hosts edit). That UAC
-   prompt is the "signing" you were sensing; it's a runtime elevation, not a build
-   step.
-
-So: build → run → approve the UAC prompt. That's it.
-
-## Prerequisites (both paths)
-
-- **Windows 10/11** with administrator rights (the UAC prompt needs to succeed).
-- **Docker Desktop** with the **WSL 2 backend** enabled, running.
-- **Go 1.27** (`go version` must report 1.27.x — this repo needs it).
-- **Git**.
-- The repo cloned somewhere (`git clone …/vip`).
-
-This repo uses the standard-library `encoding/json/v2` package available in Go 1.27.
-
----
-
-## Path A — Build & run inside WSL (recommended)
-
-This exercises the real WSL→Windows bridge: a Linux binary that detects WSL and
-edits the **Windows** hosts file + Windows cert store via `powershell.exe`.
-
-### 1. Install Go 1.27 in your WSL distro
-
-```bash
-# in WSL (Ubuntu etc.)
-cd /tmp
-curl -LO https://go.dev/dl/go1.27.0.linux-amd64.tar.gz   # match 1.27.x
-sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.27.0.linux-amd64.tar.gz
-echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc
-go version   # go1.27.x linux/amd64
-```
-
-### 2. Enable Docker Desktop WSL integration
-
-Docker Desktop → Settings → Resources → WSL Integration → enable your distro.
-Confirm in WSL: `docker version` shows both client and server.
-
-### 3. Confirm the WSL→Windows bridge works (the feature depends on it)
-
-```bash
-powershell.exe -NoProfile -Command "Write-Output ok"   # must print: ok
-```
-
-If `powershell.exe` isn't found, WSL interop is disabled — enable it in
-`/etc/wsl.conf` (`[interop] enabled=true`) and `wsl --shutdown` from Windows.
-
-### 4. Build
-
-```bash
-cd /path/to/vip
-CGO_ENABLED=0 go build -buildvcs=false -o bin/vip-next ./cmd/vip-next
-./bin/vip-next --version
-```
-
-(`make build` also works if you have `make`; it additionally bundles the
-`go-search-replace` helper, which this feature does not need.)
-
-### 5. Run it
-
-```bash
-./bin/vip-next dev-env create --slug wintest --start
-```
-
-When it reaches the hosts/CA step (after WordPress install), a **UAC prompt pops
-on the Windows desktop**. Approve it. Behind it: the WPVIP Local CA is added to
-the Windows Root store and `wintest.vipdev.site` (+ `-pma`/`-mailpit` if enabled)
-is written to the Windows hosts file.
-
-> Note: env data lives under your WSL home: `~/.local/share/vip/dev-environment/`.
-
----
-
-## Path B — Build & run natively on Windows (PowerShell)
-
-The binary is a native `.exe` (`GOOS=windows`) → same Windows-hosts/cert path,
-just without the WSL bridge.
-
-### 1. Install Go 1.27 for Windows
-
-From <https://go.dev/dl/> (the `.msi`), or `winget install GoLang.Go`. Open a
-**new** PowerShell so `go` is on PATH. `go version` → 1.27.x.
-
-### 2. Build (PowerShell)
-
-```powershell
-cd C:\path\to\vip
-$env:CGO_ENABLED  = "0"
-go build -buildvcs=false -o vip-next.exe .\cmd\vip-next
-.\vip-next.exe --version
-```
-
-(`make` usually isn't present on Windows — use the raw `go build` above.)
-
-### 3. Run it
-
-```powershell
-.\vip-next.exe dev-env create --slug wintest --start
-```
-
-Run from an **ordinary** (non-admin) PowerShell — the tool raises its own UAC
-prompt for the hosts/cert step. Env data lands at
-`C:\Users\<you>\.local\share\vip\dev-environment\`.
-
----
-
-## Verify the feature worked
-
-```powershell
-# CA is in the Windows Root store:
-certutil -store Root | Select-String "WPVIP"
-
-# Managed hosts block is present (note the BEGIN/END markers):
-Get-Content C:\Windows\System32\drivers\etc\hosts | Select-String -Context 0,5 "BEGIN vip-dev-env"
-
-# The site resolves to loopback and is reachable:
-ping wintest.vipdev.site            # -> 127.0.0.1
-# then open https://wintest.vipdev.site:<port>/ in a browser (no cert warning)
-```
-
-From **WSL**, confirm it edited the _Windows_ file (not WSL's `/etc/hosts`):
-
-```bash
-grep -A6 "BEGIN vip-dev-env" /mnt/c/Windows/System32/drivers/etc/hosts
-```
-
-### The actual offline test
-
-1. Start the env (hosts written).
-2. Turn off Wi-Fi / pull the network (or block DNS).
-3. Reload `https://wintest.vipdev.site:<port>/` — it must still resolve, because
-   the hosts file (not public DNS) is doing the work now. That's the whole point.
-
-### Re-prompt behavior
-
-Re-running `dev-env start` on an unchanged env should **not** prompt for UAC again
-(the CA is already trusted and the hosts entries already present — the
-context-aware `CATrusted` + `HostsPresent` checks short-circuit). If it prompts
-every time, that's a bug worth reporting.
-
----
-
-## Cleanup (to re-test from scratch)
-
-```powershell
-# Remove the managed hosts block: edit the file as Administrator and delete
-# everything between "# BEGIN vip-dev-env" and "# END vip-dev-env".
-notepad C:\Windows\System32\drivers\etc\hosts      # run elevated
-
-# Remove the CA from the Root store (elevated):
-certutil -delstore Root "WPVIP Local CA"
-```
-
-Or just `vip-next dev-env destroy --slug wintest`, which tears down containers and
-recomputes the hosts block (one more UAC prompt).
-
----
-
-## Known caveats on Windows/WSL
-
-- The dev-env stack (compose, Traefik proxy, setup.sh) was developed and exercised
-  primarily on macOS. The hosts/CA elevation path is new and Windows/WSL-aware, but
-  **other** parts of the stack may hit Windows path/permission quirks not yet seen.
-  If `create`/`start` fails _before_ the UAC step, capture the per-env log
-  (`…\dev-environment\wintest\logs\*.log`) — that's a separate issue from this
-  feature, worth reporting.
-- `Start-Process -Verb RunAs` cannot run non-interactively (no desktop session) —
-  it needs an interactive Windows session to show the UAC dialog. CI/headless runs
-  won't work; this is a manual test.
-- If the elevated step fails or you decline the UAC prompt, the CLI now surfaces a
-  non-zero exit (it no longer silently reports success), so you'll see an error.