@vzn/vx-reapi 0.0.635 → 0.0.637

package/README.md

@@ -12,7 +12,7 @@ npm install -D @vzn/vx @vzn/vx-reapi   # or: pnpm add -D -w · yarn add -D (-W o
 ```
 
 ```ts
-// vx.workspace.ts
+// .vx/workspace.ts
 import { defineWorkspace } from '@vzn/vx/config'
 import { reapi } from '@vzn/vx-reapi'
 
@@ -22,6 +22,11 @@ export default defineWorkspace({
 })
 ```
 
+Off CI a run reads the remote and does not write it unless its policy names
+the remote. Give the write credential only to the default branch's CI and a
+read-only one to laptops and pull request jobs: the server's token is the
+boundary (`docs/security.md` § Cache poisoning).
+
 `ReapiRemoteCache` is the layer class behind `reapi()`, for a workspace that
 composes cache layers by hand. The package exports `reapi`, `ReapiPluginOptions`,
 `ReapiRemoteCache` and its `ReapiOptions`; the wire client, the Merkle
@@ -134,10 +139,11 @@ held to the git blob id the key folded for it. A file edited or removed
 in between (an edit mid-run under `vx watch`) still runs, but the
 execution is not recorded under a key that no longer describes it; the
 record once replayed the edited outputs on every machine after the file
-was restored. The project's own `package.json`, which the key folds
-whether or not a glob lists it, is always in the input root.
+was restored. The input root holds exactly the files the key folded: core
+keys no package file, so a project's `package.json` is in it only as a
+listed input (`@vzn/vx-lockfile` lists it on every cached task).
 
-This matters most under `--download=none`, where deferral leaves no
+This matters most under `--cache-download=none`, where deferral leaves no
 local cache entry behind, so vx's own probe misses on every later run
 and the record is what makes the second run cheap. Records are checked
 against the CAS first (`FindMissingBlobs`) — the action cache and the
@@ -187,7 +193,9 @@ generated files. Only what a declared glob names (or what sits under a
 directory it names) is written back; the rest stays as it is on disk.
 Writing all of it once put the worker's copy of the sources over the
 user's, so an edit made while the action ran was lost. A directory a
-literal glob names is written whole.
+literal glob names is written whole. Where a write really lands, after
+the result's own links are placed, must be declared too: a declared link
+to `.git/hooks` and a declared directory under it wrote a hook.
 
 ## The existence probe confirms the artifact, not just the entry
 
@@ -408,8 +416,7 @@ A cache-only server (bazel-remote advertises `exec_enabled: false`) makes the
 plugin **decline the executor with a warning** rather than submit work that
 will never be answered. Only cacheable tasks are eligible — a task with no
 `cache` block has no described inputs, so a worker would run it against an
-empty input root. A cacheable task's root holds its declared input files
-and its project's `package.json`.
+empty input root. A cacheable task's root holds its declared input files.
 
 Verified end-to-end against a live NativeLink scheduler + worker: input tree
 uploaded, QUEUED → EXECUTING → COMPLETED streamed, stdout returned inline,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-reapi",
-  "version": "0.0.635",
+  "version": "0.0.637",
   "license": "MIT",
   "description": "Bazel Remote Execution API plugin for vx — remote cache (ActionCache + CAS) against NativeLink, BuildBuddy, Buildbarn or bazel-remote.",
   "keywords": [
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.635"
+    "@vzn/vx": "^0.0.637"
   },
   "repository": {
     "type": "git",

package/src/executor.ts

@@ -802,14 +802,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
         symlinkGrafts.push(...(g.symlinks ?? []))
       }
 
-      // The key folds the project's package.json whether or not a glob
-      // lists it, so the worker sees it too: a `"type": "module"` changes
-      // what a bundler emits, and a tree without it ran as another task.
       const expected = new Map(req.inputs.files.map((f) => [f.path, f.digest]))
-      const packageJson = projectRel === '' ? 'package.json' : `${projectRel}/package.json`
-      if (req.inputs.packageJsonDigest !== '' && !expected.has(packageJson)) {
-        expected.set(packageJson, req.inputs.packageJsonDigest)
-      }
       const inputPaths = [...expected.keys(), ...localUpstreamPaths]
       const tree = await buildInputTree({
         expected,
@@ -1008,7 +1001,7 @@ export function reapiExecutor(client: ReapiClient, opts: ReapiExecutorOptions =
 
       // A remote-only task's outputs stay remote — materialising node_modules
       // onto the submitter's disk is precisely what `remote: 'only'` forbids.
-      // `--download=none` defers the same transfer WITHOUT making it
+      // `--cache-download=none` defers the same transfer WITHOUT making it
       // permanent: the bytes stay in the CAS and core gets a closure to pull
       // them if a locally-placed consumer turns out to need them.
       // Started before the logs are read, not after: a server that keeps
@@ -1418,7 +1411,14 @@ export async function materialiseOutputs(
     const rel = toPosix(path.relative(req.workspaceRoot, abs))
     return declared.includes(rel) || matchers.some((m) => m.match(rel))
   }
-  const fence = new Fence(req.workspaceRoot)
+  // A declared output, or a path under one a literal glob names whole.
+  const underDeclared = (rel: string): boolean => {
+    for (let r = rel; r !== '.' && r !== ''; r = path.posix.dirname(r)) {
+      if (declared.includes(r) || matchers.some((m) => m.match(r))) return true
+    }
+    return false
+  }
+  const fence = new Fence(req.workspaceRoot, underDeclared)
   // A file or link no declared glob names is neither fetched nor written:
   // the workspace root was the only fence, so a result (or a record planted
   // in the action cache) could write `.git/hooks/post-checkout` 0755 or
@@ -1435,6 +1435,7 @@ export async function materialiseOutputs(
     const abs = fence.lexical(req.cwd, f.path)
     await fence.dir(path.dirname(abs))
     await makeDir(path.dirname(abs), created)
+    await fence.landing(abs)
     // Inlined only when it has bytes: an ActionResult read back through
     // proto-loader (the execution-record replay) carries `contents` as an
     // EMPTY Buffer on every file, and taking that as inline wrote each
@@ -1506,11 +1507,35 @@ class Fence {
   private readonly checked = new Set<string>()
   private readonly links: { abs: string; target: string }[] = []
   private readonly root: string
+  private readonly realDirs = new Map<string, Promise<string>>()
 
-  constructor(root: string) {
+  constructor(
+    root: string,
+    /** A workspace-relative path the task declared as output, or under one. */
+    private readonly declared: (rel: string) => boolean = () => true,
+  ) {
     this.root = path.resolve(root)
   }
 
+  /**
+   * Where a file write really lands, judged after the result's links are
+   * placed: a declared link to `.git/hooks`, then a declared directory
+   * under it, wrote an executable hook (both inside the root, so the
+   * containment checks passed). The landing must itself be declared.
+   */
+  async landing(abs: string): Promise<void> {
+    this.realRoot ??= await realpath(this.root).catch(() => this.root)
+    const dir = path.dirname(abs)
+    let real = this.realDirs.get(dir)
+    if (real === undefined) {
+      real = realpath(dir)
+      this.realDirs.set(dir, real)
+    }
+    const rel = toPosix(path.relative(this.realRoot, path.join(await real, path.basename(abs))))
+    if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel) || !this.declared(rel))
+      throw this.refuse(abs)
+  }
+
   /** `rel` joined under `base`, refused when the join leaves the root. */
   lexical(base: string, rel: string): string {
     // A NUL reached the file system as a raw ERR_INVALID_ARG_VALUE.
@@ -1763,6 +1788,7 @@ async function materialiseTree(
         missing(abs, f.digest.hash, abs)
         return
       }
+      await fence.landing(abs)
       await writeOutput(abs, bytes, created)
       if (f.is_executable) await chmod(abs, 0o755)
       // NodeProperties.unix_mode is authoritative when the server sent it.

package/src/index.ts

@@ -12,8 +12,7 @@
 import { readFileSync } from 'node:fs'
 import {
   definePlugin,
-  LayeredCache,
-  type CacheLayer,
+  type RemoteCacheLayer,
   type TaskExecutor,
   type VxPlugin,
   UserError,
@@ -84,7 +83,7 @@ export interface ReapiPluginOptions extends Partial<
 }
 
 /**
- * Declare in `vx.workspace.ts`; the local store is the floor beneath it and is
+ * Declare in `.vx/workspace.ts`; the local store is the floor beneath it and is
  * read first, so the remote is asked only on a local miss:
  *
  * ```ts
@@ -257,7 +256,7 @@ export function reapi(options: ReapiPluginOptions = {}): VxPlugin {
       executorClient?.close()
       executorClient = undefined
       // The cache layer holds a client too, and `RemoteCacheLayer` has no
-      // close hook for core to call — `LayeredCache.close()` closes only the
+      // close hook for core to call — core closes only its
       // LOCAL handle. Closing it here is lifecycle hygiene rather than a
       // measured fix: @grpc/grpc-js pools subchannels per target, so 20
       // unclosed clients were MEASURED to share one connection. It matters
@@ -266,19 +265,13 @@ export function reapi(options: ReapiPluginOptions = {}): VxPlugin {
       remoteCache?.close()
       remoteCache = undefined
     },
-    cache(ctx): CacheLayer | undefined {
+    cache(ctx): RemoteCacheLayer | undefined {
       const conn = connection(options)
       if (conn === undefined) return undefined
-      const remote = new ReapiRemoteCache({ ...conn, onWarn: (m) => ctx.warn(m) })
-      remoteCache = remote
-      // Compose over the local handle the host opened: reads try local, then
-      // remote (hydrating local on a remote hit); writes go local immediately
-      // and the remote upload drains in the background. All of that is core's
-      // LayeredCache — this plugin supplies only the wire.
-      return new LayeredCache(ctx.localCache, remote, {
-        policy: ctx.policy,
-        onRemoteError: (err) => ctx.warn(`vx/reapi: ${err.message}`),
-      })
+      // Only the wire: core layers it over the local store (reads try local,
+      // then remote, hydrating local on a hit; uploads drain in the background).
+      remoteCache = new ReapiRemoteCache({ ...conn, onWarn: (m) => ctx.warn(m) })
+      return remoteCache
     },
   })
 }