@vzn/vx 0.0.632 → 0.0.634

package/docs/security.md

@@ -0,0 +1,209 @@
+# Security model
+
+What vx trusts, what it checks, what the sandbox stops and what it does
+not, and how to report a problem. Report a vulnerability privately
+through GitHub's private vulnerability reporting on
+[vznjs/vx](https://github.com/vznjs/vx/security) (Security → Report a
+vulnerability), never in a public issue.
+
+## What vx trusts
+
+- **Your configs.** `vx.config.ts` and `vx.workspace.ts` are programs vx
+  runs in its own process. A config can do anything you can: vx
+  validates what it returns, not what it does. What a config imports
+  must already be installed: vx runs Bun with `--no-install`, so an
+  import no `node_modules` provides is refused, never fetched from the
+  registry (L-22).
+- **Your plugins.** A plugin is code you imported. It runs in vx's
+  process with a config's reach; vx checks the shape of what it hands
+  back and isolates a telemetry plugin's failures, nothing more.
+- **Your lockfile and your repo.** vx parses a lockfile (and
+  `turbo.json` or an Nx graph when migrating) into keys and refuses one
+  it cannot read, naming the file. A lockfile that names another
+  install is a different key, never a code path.
+- **Whoever can write your remote cache.** A cache key names the
+  inputs, not the bytes, so a store that answers a key with bytes of its
+  choosing is trusted as a writer, as it is in every action cache. Use a
+  store only your builds write to, or `turboCache()`'s signature key,
+  which refuses an artifact a keyholder did not sign. A job you do not
+  trust (a fork's pull request) reads at most: `--cache=local:rw,remote:r`,
+  or the tools' own `TURBO_REMOTE_CACHE_READ_ONLY`, `TURBO_CACHE` and
+  `NX_SKIP_REMOTE_CACHE`, which the cache plugins honour (L-34).
+
+## Cache poisoning
+
+A pull request that can write the cache the default branch reads can
+plant bytes main later replays (CREEP, CVE-2025-36852). The boundary is
+the credential, enforced by the cache server: the default branch's job
+holds a token that writes the trusted keys, and a pull request's job
+holds one that cannot (read-only, or confined by the server to its own
+namespace), or none.
+
+`cacheScope` is the client half. `'pr-123'` reads its own keys,
+then the trusted ones, and writes only its own, which `github()` sets on
+Actions (`pr-<n>`, `ref-<name>`; the default branch stays trusted)
+and `VX_CACHE_SCOPE` sets on any CI.
+It keeps honest runs apart and stops a non-hermetic PR build from
+landing where main reads; it is not a boundary, since the PR's own
+config decides it and any run holding a write credential can write any
+key.
+
+A boundary the server holds, with bazel-remote and `@vzn/vx-reapi`: reads
+are open, writes need a password, and only main's push job has it.
+
+```sh
+htpasswd -cB /etc/bazel-remote/htpasswd ci   # the write credential
+bazel-remote --dir /data --max_size 50 --grpc_address 0.0.0.0:9092 \
+  --htpasswd_file /etc/bazel-remote/htpasswd --allow_unauthenticated_reads
+```
+
+```ts
+// vx.workspace.ts: the header only where the secret is set
+reapi({
+  endpoint: 'grpcs://cache.example.com:9092',
+  headers: process.env.CACHE_AUTH ? { authorization: `Basic ${process.env.CACHE_AUTH}` } : {},
+})
+```
+
+```yaml
+# .github/workflows/ci.yml: CACHE_AUTH (base64 of ci:<password>) is a
+# secret of the `cache-write` environment, whose only deployment branch
+# is main, so no other branch's workflow can read it
+jobs:
+  build:
+    if: github.event_name != 'push' || github.ref != 'refs/heads/main'
+    steps:
+      - run: vx run build --all
+  build-main:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment: cache-write
+    env:
+      CACHE_AUTH: ${{ secrets.CACHE_AUTH }}
+    steps:
+      - run: vx run build --all
+```
+
+A pull request's job has no `CACHE_AUTH`, so the server refuses its
+writes whatever its config says. Never give the write secret to a
+`pull_request_target`, `issue_comment` or `workflow_run` job that checks
+out a pull request's code: it runs with main's ref and secrets, and
+`github()` scopes it `pr-<n>` only on the client side.
+
+## What vx checks on bytes it did not write
+
+Every artifact that arrives from a remote, and every one read back from
+the local store:
+
+- ends in a CRC-32 of its entries: a byte changed in transit or at rest
+  makes the hit a miss, never a replay of the damaged bytes;
+- on arrival, records the cache key it was packed under, and is
+  refused under another (a local read-back is not re-checked);
+- on arrival, carries only the files the task declares as outputs;
+- lands each file under the task's project or declared workspace path:
+  traversal (`..`, `.`, absolute names) is refused before anything
+  lands, a refused archive leaves nothing behind, and links and devices
+  are never written; a seeded fuzz of hostile archives holds this;
+- is bounded: a decompression bomb, an oversized header or body, and a
+  remote answer larger than asked for are refused as they are read.
+
+Remote execution (`@vzn/vx-reapi`) holds each blob to its digest, and
+writes only the server's outputs a declared glob names, inside the
+workspace, through no link that leads out of it.
+
+## What the sandbox stops
+
+A task with `exec.sandbox` runs where only what it declares exists:
+
+- reads of the workspace outside the task's project and grants fail;
+- writes outside its `allow.write` grants fail (declared outputs grant
+  none);
+- the network is closed except to the domains granted, one union per
+  run: a task granted any domain reaches every domain the run grants;
+  with none, it reaches no listener on the host's loopback and no unix
+  socket outside the workspace (L-46);
+- its temp directory, port-bridge socket and trace log are its own
+  (mode 0700), unreachable from another task and another local user;
+- the host's credential stores (`~/.ssh`, `~/.gnupg`, `~/.aws`,
+  `~/.npmrc`, `~/.netrc` and the like; the list is in the schema's
+  sandbox section) are unreadable unless `allow.read` names one (L-41);
+- vx's own cache directory, wherever `cacheDir` puts it in the
+  workspace, is a wall like `.vx`: a broad grant stops at it, and a write
+  grant that would bind it is refused (L-24);
+- a symlinked output must resolve inside its project: vx packs outputs
+  outside the sandbox, and a link to another project's file would have
+  carried that file into the cache (L-23). An output directory linked out
+  of the project refuses the task by name (X-88).
+
+An undeclared touch of the task's own files fails the task, and a failed
+task is never cached. See [Sandboxing tasks](https://vznjs.github.io/vx/guides/sandboxing/).
+
+## What it does not stop
+
+- **A task with no `exec.sandbox`.** It runs with your permissions.
+- **Reads outside the workspace root.** `~/.cache`, `/etc` and the like
+  stay readable (tools need them) and fold into no key. The credential
+  stores under home (`~/.ssh`, `~/.aws`, `~/.npmrc` and the like) are
+  not: a task reads one only when its `allow.read` names it (L-41).
+- **Resource use.** CPU, memory and disk are bounded by timeouts and the
+  artifact ceiling, not by the sandbox.
+- **A weaker sandbox where the host cannot nest one**:
+  `weakerWhenNested` in a container, a task that itself sandboxes on
+  macOS. `vx info` says what the host supports.
+
+## Agents (`vx mcp`)
+
+An agent connected to `vx mcp` can do what `vx run` can do, nothing more.
+Every tool but `runTasks` only reads. `runTasks` runs `vx run --format json`
+as a child process: the agent names tasks and sets `all`, `force`,
+`filter` and `affected`, and nothing else. A task name that starts with
+`-` is refused, a filter goes as one `--filter=` value, and a ref reaches
+git after `--end-of-options`, so no argument becomes a flag. The commands
+that run are the ones your configs declare, from the workspace root, with
+the environment `vx mcp` started with, filtered by each task's `exec.env`
+and held by its `exec.sandbox`. `force` costs a rerun, not a wrong entry:
+the key stays the same. What reaches the agent (summaries, refusals,
+`getFailures` output) is masked as described under Secrets.
+`mcp({ run: false })` takes `runTasks` away, and `mcp({ run: ['test'] })`
+limits it to those task names. An agent that
+can edit `vx.config.ts` can run anything, as you can, because configs are
+code vx trusts.
+
+## Secrets
+
+The value, of 6 characters or more, of a variable whose name holds
+`TOKEN`, `SECRET`, `KEY`, `PASSWORD`, `PASSWD` or `CREDENTIAL` (not one
+ending `_FILE`, `_PATH` or `_DIR`, nor `GIT_CONFIG_KEY_<n>`), or that a
+task lists in `exec.env.secret`, and the password of a URL
+(`scheme://user:<password>@`) in any variable's value, is printed as `***` wherever vx shows, stores or
+exports it: task output, the stdout a hit replays, commands, an
+executor's error, telemetry,
+`vx show` and `vx mcp`'s `listTasks` (L-26). Values in the run history are digests under a per-store
+salt, and what follows `--` on the command line reaches telemetry as a
+count, not a quote, a secret before it masked (L-44). A remote executor (`@vzn/vx-reapi`) receives a
+task's `exec.env.define` values and the `cache.inputs.env` values its
+local child gets, never `passThrough`; those values sit unmasked in the
+action's Command, which the remote stores in its CAS, as Bazel's
+`--action_env` does, so a secret a remote task needs is trusted to that
+remote. `vx lock` refuses to write a lock holding a secret value: the lock is
+committed (L-42).
+
+Masking covers the text vx shows and stores, not a task's outputs: they
+are cached and uploaded as the task wrote them, so a build that bakes a
+secret into a file (a server bundle reading `process.env.API_KEY`) hands
+it to every reader of the remote cache. Keep secrets out of cached
+outputs, or give that task no `cache`. vx does not scan outputs for
+secret values: a name-based match would refuse public `*_KEY` values too.
+
+## Releases
+
+Release binaries carry a build-provenance attestation
+(`gh attestation verify vx-<target> --repo vznjs/vx`); `vx upgrade`
+checks each download's SHA-256 before it replaces anything and stages it in a fresh directory, never a name another user could plant a link at, which proves
+the bytes arrived intact, not who built them: the digest comes from the
+release that serves the asset, and no signature is checked (owner,
+2026-10-03: no release signing key for now); npm packages
+publish with provenance; every third-party action in CI runs from a
+full commit SHA; and a workflow hands an event's or a dispatcher's value
+to a script through `env`, never pasted in (a release tag is checked as a
+version first); every workflow names its token's permissions, and CI's
+is read-only. A test holds each rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.632",
+  "version": "0.0.634",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.632",
-    "@vzn/vx-linux-arm64": "0.0.632",
-    "@vzn/vx-darwin-x64": "0.0.632",
-    "@vzn/vx-darwin-arm64": "0.0.632"
+    "@vzn/vx-linux-x64": "0.0.634",
+    "@vzn/vx-linux-arm64": "0.0.634",
+    "@vzn/vx-darwin-x64": "0.0.634",
+    "@vzn/vx-darwin-arm64": "0.0.634"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -35,6 +35,13 @@
     "config",
     "schemas",
     "skills",
+    "docs/cli.md",
+    "docs/schema.md",
+    "docs/caching.md",
+    "docs/execution.md",
+    "docs/patterns.md",
+    "docs/security.md",
+    "docs/features.md",
     "launcher.cjs",
     "README.md",
     "LICENSE"

package/schemas/docs.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx docs <query> --format json",
+  "description": "The reference sections holding every word of the query, best first.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["query", "hits"],
+  "properties": {
+    "query": { "type": "string", "description": "the query's words, lowercased" },
+    "hits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["page", "heading", "url", "text"],
+        "properties": {
+          "page": { "type": "string", "description": "the page: cli, schema, caching …" },
+          "heading": {
+            "type": "string",
+            "description": "the section's heading; empty for a page's opening"
+          },
+          "url": { "type": "string", "description": "the section on the site" },
+          "text": { "type": "string", "description": "the section's markdown, heading included" }
+        }
+      }
+    }
+  }
+}

package/schemas/error.json

@@ -16,7 +16,11 @@
           "type": "string",
           "description": "Stable; branch on it. VX_E_USAGE, VX_E_UNKNOWN_COMMAND, VX_E_UNKNOWN_TASK, VX_E_UNKNOWN_PROJECT, VX_E_NO_HISTORY, VX_E_AMBIGUOUS, VX_E_CONFIG, VX_E_CYCLE, VX_E_NO_WORKSPACE, VX_E_CACHE_VERSION, VX_E_REFUSED, VX_E_FS, VX_E_FDS, VX_E_INTERNAL."
         },
-        "message": { "type": "string", "description": "The refusal in prose; may change." }
+        "message": { "type": "string", "description": "The refusal in prose; may change." },
+        "docs": {
+          "type": "string",
+          "description": "For a core code (VX_E_…): its section of the CLI reference, which says what to do. A plugin's code has none."
+        }
       }
     }
   }

package/schemas/init.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx init --dry --format json",
+  "description": "What vx init (or vx-migrate) would write, nothing written. In a Turbo or Nx repo the plan is vx-migrate's.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dry", "source", "files", "kept", "replaced", "todos", "notes", "next"],
+  "properties": {
+    "dry": { "const": true },
+    "source": {
+      "type": "string",
+      "description": "what the plan maps: package.json scripts, turbo.json, nx graph, lerna.json …"
+    },
+    "files": {
+      "type": "array",
+      "description": "each file the run would write, root-relative, with its whole text",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "contents"],
+        "properties": { "path": { "type": "string" }, "contents": { "type": "string" } }
+      }
+    },
+    "kept": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "configs already here that the run leaves as they are"
+    },
+    "replaced": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "files of another extension the run would delete for the new ones"
+    },
+    "todos": {
+      "type": "array",
+      "description": "what the mapping could not settle, one reason with the tasks it names",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reason", "tasks"],
+        "properties": {
+          "reason": { "type": "string" },
+          "tasks": { "type": "array", "items": { "type": "string" }, "description": "project#task" }
+        }
+      }
+    },
+    "notes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "the report's notes"
+    },
+    "next": {
+      "type": ["string", "null"],
+      "description": "the command to type after the real run; null where the plan names none"
+    }
+  }
+}

package/schemas/lock.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx lock --check --format json",
+  "description": "The lock audit: exit 0 when upToDate, else 1 with each drift in problems.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["upToDate", "audited", "notAudited", "problems"],
+  "properties": {
+    "upToDate": { "type": "boolean" },
+    "audited": { "type": "integer", "description": "projects with a vx.config, each audited" },
+    "notAudited": {
+      "type": "integer",
+      "description": "projects without a vx.config: nothing to freeze, never audited"
+    },
+    "problems": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "one line per drift, as the plain audit prints it on stderr; a missing lock is one"
+    }
+  }
+}

package/schemas/plan.json

@@ -6,6 +6,10 @@
   "additionalProperties": false,
   "required": ["tasks"],
   "properties": {
+    "affectedBase": {
+      "type": "string",
+      "description": "under --affected: the ref the diff was taken against (a bare --affected guesses it: origin/HEAD, a trunk branch, else HEAD~1)"
+    },
     "tasks": {
       "type": "array",
       "items": {

package/skills/vx/SKILL.md

@@ -21,6 +21,9 @@ vx run build --all --format json    # the result as JSON on stdout; logs go to s
 The exit code is the verdict: `0` every task passed or hit the cache, `1` a
 task failed or was skipped, or the command was refused. `--format json`
 prints `schemas/summary.json` (`runId`, `ok`, `exitCode`, a row per task).
+A refusal under `--format json` is one line on stdout,
+`{"ok":false,"error":{"code","message","docs"}}`: branch on `code`;
+`docs` (or `vx docs <code>` offline) says what to do.
 Without a TTY a missing task name never prompts: vx exits 1 and lists the
 tasks it found.
 
@@ -31,7 +34,10 @@ vx show --format json                          # projects, their tasks and depen
 vx run test --affected=origin/main --dry=json  # what would run, cache hit or miss, and why
 ```
 
-Under `--affected`, each kept task in `--dry=json` carries `affected`:
+Under `--affected`, `--dry=json` states `affectedBase` (the ref it diffed
+against; name one, `--affected=origin/main`, rather than trust the guess)
+and each task you asked for carries `affected` (a dependency it pulls in
+does not):
 `{ kind, file?, project?, via? }`, where `kind` is `input` (a changed file
 is one of its inputs), `project`, `package`, `named` or `selected`, and
 `via` is the `dependsOn` chain that carried the change.
@@ -64,10 +70,11 @@ vx info --format json   # vx and Bun versions, projects, config errors, plugins,
 When `@vzn/vx-mcp` is a plugin in `vx.workspace.ts`, `vx mcp` serves the
 same facts and runs tasks. Adoption does not add it: install
 `@vzn/vx-mcp` and put `mcp()` (from `'@vzn/vx-mcp'`) in `plugins`. Its tools: `listTasks`, `getCacheStats`,
-`getRunHistory`, `explainCacheKey`, `whyDidThisRerun`, `getFailures`, `getTaskLog`, `getConfig`,
+`getRunHistory`, `explainCacheKey`, `whyDidThisRerun`, `getFailures`, `getTaskLog`, `getConfig`, `checkLock`, `pruneCache`, `planInit`, `searchDocs`,
 `getWorkspaceInfo`, `runTasks`, `planTasks`. `runTasks` answers what
 `vx run <tasks> --format json` prints, `planTasks` what
-`vx run <tasks> --dry=json` prints; the others only read.
+`vx run <tasks> --dry=json` prints, `pruneCache` evicts only with
+`dryRun: false`; the others only read.
 
 ## Rules
 
@@ -78,6 +85,9 @@ same facts and runs tasks. Adoption does not add it: install
   does not re-run a task, the file is not one of its inputs. Fix the
   config, do not force.
 - Every JSON shape is a JSON Schema in `node_modules/@vzn/vx/schemas/`.
+- Offline reference: `vx docs <words> --format json` searches the CLI, config
+  and cache pages that ship with vx; the sections holding every word print
+  whole.
 - Docs as markdown: https://vznjs.github.io/vx/llms.txt (its index).
   When that host is unreachable, the same pages are
   `https://raw.githubusercontent.com/vznjs/vx/main/packages/vx-docs/src/content/docs/<page>.md`: