@automattic/vip 4.0.10 → 4.0.13

package/dist/lib/rechallenge/link.js

@@ -0,0 +1,167 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = createRechallengeLink;
+var _core = require("@apollo/client/core");
+var _debug = _interopRequireDefault(require("debug"));
+var _graphql = require("graphql");
+var _flow = require("./flow");
+var _tokenCache = _interopRequireDefault(require("./token-cache"));
+var _types = require("./types");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const debug = (0, _debug.default)('@automattic/vip:rechallenge:link');
+function operationDefinition(doc) {
+  return doc.definitions.find(def => def.kind === _graphql.Kind.OPERATION_DEFINITION);
+}
+function isMutation(doc) {
+  return operationDefinition(doc)?.operation === _graphql.OperationTypeNode.MUTATION;
+}
+function primaryMutationFieldName(doc) {
+  const op = operationDefinition(doc);
+  if (!op || op.operation !== _graphql.OperationTypeNode.MUTATION) {
+    return null;
+  }
+  const first = op.selectionSet.selections.find(sel => sel.kind === _graphql.Kind.FIELD);
+  return first?.name.value ?? null;
+}
+function extractElevatedPermission(result) {
+  const errors = result.errors ?? [];
+  for (const err of errors) {
+    const ext = err.extensions ?? {};
+    if (ext.code !== _types.ELEVATED_PERMISSION_ERROR_CODE) {
+      continue;
+    }
+    const rechallenge = ext.rechallenge;
+    if (rechallenge && typeof rechallenge.createSessionPath === 'string' && typeof rechallenge.statusPathTemplate === 'string' && typeof rechallenge.exchangePathTemplate === 'string' && typeof rechallenge.elevatedHeaderName === 'string') {
+      return {
+        rechallenge
+      };
+    }
+  }
+  return null;
+}
+function attachElevatedHeader(operation, headerName, token) {
+  const ctx = operation.getContext();
+  const headers = {
+    ...ctx.headers
+  };
+  headers[headerName] = token.token;
+  operation.setContext({
+    ...ctx,
+    headers
+  });
+}
+const DEFAULT_HEADER = 'x-elevated-token';
+function createRechallengeLink() {
+  return new _core.ApolloLink((operation, forward) => {
+    const scope = primaryMutationFieldName(operation.query);
+    const eligible = isMutation(operation.query) && Boolean(scope);
+    return new _core.Observable(observer => {
+      let retrying = false;
+      let cancelled = false;
+      let firstSub = null;
+      let retrySub = null;
+      const abortController = new AbortController();
+      const preflight = async () => {
+        if (!eligible || !scope) {
+          return;
+        }
+        const cached = await _tokenCache.default.get(scope);
+        if (cached) {
+          attachElevatedHeader(operation, cached.headerName || DEFAULT_HEADER, cached);
+        }
+      };
+      const handleRetry = async (result, elevated) => {
+        retrying = true;
+        const headerName = elevated.rechallenge.elevatedHeaderName || DEFAULT_HEADER;
+        let token;
+        try {
+          token = await (0, _flow.runRechallenge)({
+            requestedOperation: scope,
+            rechallenge: elevated.rechallenge,
+            interactive: (0, _flow.isInteractiveContext)(),
+            wait: (0, _flow.shouldWaitForRechallenge)(),
+            signal: abortController.signal
+          });
+        } catch (err) {
+          debug('rechallenge flow failed: %o', err);
+          if (cancelled || observer.closed) {
+            return;
+          }
+          // Surface the original elevated-permission error to upstream
+          // so errorLink and consumers see it.
+          observer.next(result);
+          observer.complete();
+          return;
+        }
+        if (cancelled || observer.closed) {
+          return;
+        }
+        attachElevatedHeader(operation, headerName, token);
+        try {
+          retrySub = forward(operation).subscribe({
+            next: res => observer.next(res),
+            error: err => observer.error(err),
+            complete: () => observer.complete()
+          });
+        } catch (err) {
+          if (cancelled || observer.closed) {
+            return;
+          }
+          observer.error(err);
+        }
+      };
+      const start = async () => {
+        try {
+          await preflight();
+        } catch (err) {
+          debug('preflight error: %o', err);
+        }
+        if (cancelled || observer.closed) {
+          return;
+        }
+        try {
+          firstSub = forward(operation).subscribe({
+            next: result => {
+              if (retrying || !eligible || !scope) {
+                observer.next(result);
+                return;
+              }
+              const elevated = extractElevatedPermission(result);
+              if (!elevated) {
+                observer.next(result);
+                return;
+              }
+              void handleRetry(result, elevated);
+            },
+            error: err => observer.error(err),
+            complete: () => {
+              if (!retrying) {
+                observer.complete();
+              }
+            }
+          });
+        } catch (err) {
+          if (cancelled || observer.closed) {
+            return;
+          }
+          observer.error(err);
+        }
+      };
+      void start().catch(err => {
+        if (cancelled || observer.closed) {
+          return;
+        }
+        observer.error(err);
+      });
+      return () => {
+        cancelled = true;
+        // Abort any in-flight rechallenge polling so the loop, its tracking
+        // events, and the token-cache write stop instead of running to expiry.
+        abortController.abort();
+        firstSub?.unsubscribe();
+        retrySub?.unsubscribe();
+      };
+    });
+  });
+}

package/dist/lib/rechallenge/open-browser.js

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.openBrowser = openBrowser;
+var _debug = _interopRequireDefault(require("debug"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const debug = (0, _debug.default)('@automattic/vip:rechallenge:open-browser');
+
+/** Opens a URL in the default browser. Wraps the ESM-only `open` package. */
+async function openBrowser(url) {
+  try {
+    const {
+      default: open
+    } = await import('open');
+    await open(url, {
+      wait: false
+    });
+  } catch (err) {
+    debug('Failed to open(%s): %o', url, err);
+  }
+}

package/dist/lib/rechallenge/token-cache.js

@@ -0,0 +1,113 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _debug = _interopRequireDefault(require("debug"));
+var _constants = require("../api/constants");
+var _keychain = require("../keychain");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const debug = (0, _debug.default)('@automattic/vip:rechallenge:cache');
+// Storage strategy: a single keychain entry holds a JSON map { [scope]: ElevatedToken }.
+// The vip-cli Keychain interface (src/lib/keychain/keychain.ts) is service-only — there
+// is no separate account argument — so per-scope entries under the keytar model would
+// require a different keying scheme. The single-blob approach also keeps clearAll() cheap.
+// This is marked subject-to-change in the spec pending security review.
+const BASE_SERVICE = 'vip-go-cli:elevated';
+function serviceName() {
+  if (_constants.API_HOST === _constants.PRODUCTION_API_HOST) {
+    return BASE_SERVICE;
+  }
+  const sanitized = _constants.API_HOST.replace(/[^a-z0-9]/gi, '-');
+  return `${BASE_SERVICE}:${sanitized}`;
+}
+let inMemory = null;
+async function read() {
+  if (inMemory) {
+    return inMemory;
+  }
+  const keychain = await (0, _keychain.getKeychain)();
+  const raw = await keychain.getPassword(serviceName());
+  if (!raw) {
+    inMemory = {};
+    return inMemory;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      inMemory = parsed;
+    } else {
+      debug('Elevated token blob had unexpected shape; resetting');
+      inMemory = {};
+      await keychain.deletePassword(serviceName());
+    }
+  } catch (err) {
+    debug('Failed to parse elevated token blob; resetting (%o)', err);
+    inMemory = {};
+    await keychain.deletePassword(serviceName());
+  }
+  return inMemory;
+}
+async function write(blob) {
+  inMemory = blob;
+  const keychain = await (0, _keychain.getKeychain)();
+  if (Object.keys(blob).length === 0) {
+    await keychain.deletePassword(serviceName());
+  } else {
+    await keychain.setPassword(serviceName(), JSON.stringify(blob));
+  }
+}
+function isExpired(token) {
+  const exp = Date.parse(token.expiresAt);
+  if (Number.isNaN(exp)) {
+    return true;
+  }
+  // Treat tokens within the next 5 seconds as effectively expired.
+  return Date.now() >= exp - 5_000;
+}
+async function get(scope) {
+  const blob = await read();
+  const token = blob[scope];
+  if (!token) {
+    return null;
+  }
+  if (isExpired(token)) {
+    debug('Cached elevated token for %s is expired; evicting', scope);
+    const {
+      [scope]: _evicted,
+      ...rest
+    } = blob;
+    await write(rest);
+    return null;
+  }
+  return token;
+}
+async function set(scope, token) {
+  const blob = await read();
+  blob[scope] = token;
+  await write(blob);
+}
+async function clearScope(scope) {
+  const blob = await read();
+  if (scope in blob) {
+    const {
+      [scope]: _removed,
+      ...rest
+    } = blob;
+    await write(rest);
+  }
+}
+async function clearAll() {
+  inMemory = {};
+  const keychain = await (0, _keychain.getKeychain)();
+  await keychain.deletePassword(serviceName());
+}
+function _resetInMemoryForTests() {
+  inMemory = null;
+}
+var _default = exports.default = {
+  get,
+  set,
+  clearScope,
+  clearAll,
+  _resetInMemoryForTests
+};

package/dist/lib/rechallenge/types.js

@@ -0,0 +1,15 @@
+"use strict";
+
+exports.__esModule = true;
+exports.RECHALLENGE_VERSION = exports.ELEVATED_PERMISSION_ERROR_CODE = exports.CLIENT_TYPE = void 0;
+const ELEVATED_PERMISSION_ERROR_CODE = exports.ELEVATED_PERMISSION_ERROR_CODE = 'elevated-permission-required';
+const RECHALLENGE_VERSION = exports.RECHALLENGE_VERSION = 'v2';
+const CLIENT_TYPE = exports.CLIENT_TYPE = 'cli';
+
+/** Shape of `errors[0].extensions.rechallenge` from the API. */
+
+/** Response from POST {createSessionPath}. */
+
+/** Response from GET {statusPathTemplate}. */
+
+/** Response from POST {exchangePathTemplate}. */

package/dist/lib/token.js

@@ -4,7 +4,7 @@ exports.__esModule = true;
 exports.default = exports.SERVICE = void 0;
 var _jwtDecode = require("jwt-decode");
 var _nodeCrypto = require("node:crypto");
-var _api = require("./api");
+var _constants = require("./api/constants");
 var _keychain = require("./keychain");
 // Config
 const SERVICE = exports.SERVICE = 'vip-go-cli';
@@ -92,8 +92,8 @@ class Token {
   }
   static getServiceName(modifier = '') {
     let service = SERVICE;
-    if (_api.PRODUCTION_API_HOST !== _api.API_HOST) {
-      const sanitized = _api.API_HOST.replace(/[^a-z0-9]/gi, '-');
+    if (_constants.PRODUCTION_API_HOST !== _constants.API_HOST) {
+      const sanitized = _constants.API_HOST.replace(/[^a-z0-9]/gi, '-');
       service = `${SERVICE}:${sanitized}`;
     }
     return `${service}${modifier}`;

package/docs/COMMANDER-MIGRATION.md

@@ -5,7 +5,7 @@ Goal: remove the abandoned `args` package, keep CLI behavior stable, and support
 ## Migration Outcome
 
 - `src/lib/cli/command.js` is the active Commander-backed compatibility wrapper for all bins that call `command()`.
-- `args` has been removed from `package.json` and `npm-shrinkwrap.json`.
+- `args` has been removed from `package.json` and `package-lock.json`.
 - Root command flow (`src/bin/vip.js`) now dispatches via the shared Commander wrapper again, preserving login gating and subcommand chaining.
 - Temporary side-path wrapper work has been removed (`src/lib/cli/command-commander.ts` deleted).
 

package/docs/SETUP.md

@@ -63,7 +63,7 @@ npm run build
 
 ## Usage
 
-The software runs as standalone CLI and relies on environmental variables for configuration and a few configuration files.
+The software runs as standalone CLI and relies on environment variables for configuration and a few configuration files.
 
 ### Starting up locally
 
@@ -85,15 +85,15 @@ By default, we record information about the usage of this tool using an in-house
 
 Install the software locally, run and follow the instructions to configure the access token.
 
-### Environmental variables
+### Environment variables
 
-#### Configuring environmental variables
+#### Configuring environment variables
 
-Environmental variables are configured in the shell. Use normal shell commands to set them.
+Environment variables are configured in the shell. Use normal shell commands to set them.
 
-#### List of environmental variables
+#### List of environment variables
 
-This application uses environmental variables for vital configuration information. Find a partial list below.
+This application uses environment variables for vital configuration information. Find a partial list below.
 
 TODO: Update description of the variables.
 
@@ -108,6 +108,7 @@ TODO: Update description of the variables.
 - `HTTP_PROXY`:
 - `NO_PROXY`:
 - `VIP_PROXY`: [For internal VIP use](TESTING.md#local-testing).
+- `VIP_RECHALLENGE_WAIT`: set to `1` to print the verification URL and wait for rechallenge completion on another device.
 - `VIP_USE_SYSTEM_PROXY`:
 - `WPVIP_DEPLOY_TOKEN`: For use with `vip app deploy` on sites that have custom deploys enabled.
 

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

@@ -0,0 +1,87 @@
+---
+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/helpers/generate-docs.js

@@ -65,11 +65,19 @@ const parseOutput = output => {
 		}
 
 		if ( currentSection === SECTION_COMMAND ) {
-			const [ , command, description ] = line.match( COMMAND_REGEXP );
-			result.commands.push( {
-				command,
-				description,
-			} );
+			const match = line.match( COMMAND_REGEXP );
+			if ( match ) {
+				const [ , command, description ] = match;
+				result.commands.push( {
+					command,
+					description,
+				} );
+			} else if ( result.commands.length ) {
+				// Continuation of a wrapped command description.
+				result.commands[ result.commands.length - 1 ].description += ' ' + line;
+			} else {
+				console.error( 'Unknown command line', line );
+			}
 			continue;
 		}
 		if ( currentSection === SECTION_OPTIONS ) {
@@ -79,8 +87,11 @@ const parseOutput = output => {
 					option,
 					description,
 				} );
+			} else if ( result.options.length ) {
+				// Continuation of a wrapped option description.
+				result.options[ result.options.length - 1 ].description += ' ' + line;
 			} else {
-				console.log( 'Unknown option', line );
+				console.error( 'Unknown option', line );
 			}
 			continue;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/vip",
-  "version": "4.0.10",
+  "version": "4.0.13",
   "description": "The VIP Javascript library & CLI",
   "main": "index.js",
   "bin": {
@@ -27,6 +27,10 @@
     "vip-config-software-update": "dist/bin/vip-config-software-update.js",
     "vip-db": "dist/bin/vip-db.js",
     "vip-db-phpmyadmin": "dist/bin/vip-db-phpmyadmin.js",
+    "vip-defensive-mode": "dist/bin/vip-defensive-mode.js",
+    "vip-defensive-mode-configure": "dist/bin/vip-defensive-mode-configure.js",
+    "vip-defensive-mode-disable": "dist/bin/vip-defensive-mode-disable.js",
+    "vip-defensive-mode-enable": "dist/bin/vip-defensive-mode-enable.js",
     "vip-dev-env": "dist/bin/vip-dev-env.js",
     "vip-dev-env-create": "dist/bin/vip-dev-env-create.js",
     "vip-dev-env-update": "dist/bin/vip-dev-env-update.js",
@@ -141,7 +145,7 @@
     "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@apollo/client": "4.2.3",
+    "@apollo/client": "4.2.5",
     "@automattic/vip-search-replace": "^2.0.0",
     "@json2csv/plainjs": "^7.0.3",
     "@wwa/single-line-log": "^1.1.4",
@@ -156,7 +160,7 @@
     "enquirer": "2.4.1",
     "esbuild": "^0.28.0",
     "fetch-retry": "^6.0.0",
-    "graphql": "17.0.1",
+    "graphql": "17.0.2",
     "graphql-tag": "2.12.7",
     "https-proxy-agent": "^9.0.0",
     "js-yaml": "^5.0.0",