@vzn/vx 0.0.631 → 0.0.633

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.631",
+  "version": "0.0.633",
   "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.631",
-    "@vzn/vx-linux-arm64": "0.0.631",
-    "@vzn/vx-darwin-x64": "0.0.631",
-    "@vzn/vx-darwin-arm64": "0.0.631"
+    "@vzn/vx-linux-x64": "0.0.633",
+    "@vzn/vx-linux-arm64": "0.0.633",
+    "@vzn/vx-darwin-x64": "0.0.633",
+    "@vzn/vx-darwin-arm64": "0.0.633"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"
@@ -33,6 +33,15 @@
     "index.ts",
     "src",
     "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/cache.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx cache prune --format json",
+  "description": "What the policy evicted and the orphan sweep reaped; with dryRun, what they would.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dryRun", "evicted", "bytesFreed", "orphans", "orphanBytes"],
+  "properties": {
+    "dryRun": { "type": "boolean" },
+    "evicted": {
+      "type": "integer",
+      "description": "index entries evicted by the age / size policy"
+    },
+    "bytesFreed": {
+      "type": "integer",
+      "description": "bytes those entries occupied, per the index"
+    },
+    "orphans": {
+      "type": "integer",
+      "description": "artifacts and temp files with no index row, reaped"
+    },
+    "orphanBytes": { "type": "integer" }
+  }
+}

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

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "a refusal under --format json",
+  "description": "What a verb asked for JSON prints on stdout when it refuses (exit 1). stderr carries the same refusal in prose.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "error"],
+  "properties": {
+    "ok": { "const": false },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "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." }
+      }
+    }
+  }
+}

package/schemas/info.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "vx info --format json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "vx",
+    "bun",
+    "bunSupported",
+    "git",
+    "gitStatusCache",
+    "workspaceRoot",
+    "projects",
+    "tasks",
+    "configErrors",
+    "plugins",
+    "workers",
+    "memory",
+    "cacheDir",
+    "cacheStore",
+    "cacheVersion",
+    "schemaVersion",
+    "cacheEntries",
+    "cacheBytes",
+    "cacheRetention",
+    "orphans",
+    "runs24h",
+    "hits24h",
+    "restored24h",
+    "flakyTasks",
+    "lockfile",
+    "sandbox"
+  ],
+  "properties": {
+    "vx": { "type": "string" },
+    "bun": { "type": "string" },
+    "bunSupported": { "type": "boolean" },
+    "git": { "type": ["string", "null"] },
+    "gitStatusCache": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["fsmonitor", "untrackedCache"],
+      "properties": { "fsmonitor": { "type": "boolean" }, "untrackedCache": { "type": "boolean" } }
+    },
+    "workspaceRoot": { "type": "string" },
+    "projects": { "type": "integer" },
+    "tasks": { "type": "integer" },
+    "configErrors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "message"],
+        "properties": { "path": { "type": "string" }, "message": { "type": "string" } }
+      }
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "seams"],
+        "properties": {
+          "name": { "type": "string" },
+          "seams": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "workers": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["count", "source", "cores", "cpuQuota"],
+      "properties": {
+        "count": { "type": "integer" },
+        "source": { "enum": ["workspace", "cgroup", "cores"] },
+        "cores": { "type": "integer" },
+        "cpuQuota": { "type": ["number", "null"] }
+      }
+    },
+    "memory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["usableBytes", "totalBytes", "cgroupLimitBytes"],
+      "properties": {
+        "usableBytes": { "type": "integer" },
+        "totalBytes": { "type": "integer" },
+        "cgroupLimitBytes": { "type": ["integer", "null"] }
+      }
+    },
+    "cacheDir": { "type": "string" },
+    "cacheStore": { "type": ["string", "null"] },
+    "cacheVersion": { "type": "string" },
+    "schemaVersion": { "type": "string" },
+    "cacheEntries": { "type": "integer" },
+    "cacheBytes": { "type": "integer" },
+    "cacheRetention": {
+      "type": ["object", "null"],
+      "description": "the workspace's cacheRetention, maxSize also in bytes; null when none is declared",
+      "additionalProperties": false,
+      "properties": {
+        "olderThan": { "type": "string" },
+        "maxSize": { "type": "string" },
+        "maxBytes": { "type": "integer" }
+      }
+    },
+    "orphans": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifacts", "bytes"],
+      "properties": { "artifacts": { "type": "integer" }, "bytes": { "type": "integer" } }
+    },
+    "runs24h": { "type": "integer" },
+    "hits24h": { "type": "integer" },
+    "restored24h": {
+      "type": "integer",
+      "description": "of hits24h, the hits that restored outputs; the rest were up to date"
+    },
+    "flakyTasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["taskId", "project", "task", "keys", "passes", "failures"],
+        "properties": {
+          "taskId": { "type": "string" },
+          "project": { "type": "string" },
+          "task": { "type": "string" },
+          "keys": { "type": "integer" },
+          "passes": { "type": "integer" },
+          "failures": { "type": "integer" }
+        }
+      }
+    },
+    "lockfile": { "type": "boolean" },
+    "sandbox": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["available", "reason", "declared", "untraced"],
+      "properties": {
+        "available": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "declared": { "type": "integer" },
+        "untraced": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

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"
+    }
+  }
+}