@vzn/vx-migrate 0.0.0 → 0.0.485

package/src/turbo-cache/index.ts

@@ -0,0 +1,661 @@
+// @vzn/vx-migrate (turboCache) — a vx `cache` plugin that stores artifacts in any
+// server speaking Turborepo's remote cache API (`/v8/artifacts`): Vercel's
+// hosted cache, or a self-hosted implementation of the published OpenAPI
+// spec. The wire is Turbo's; the bytes are vx's own artifacts under vx's
+// own keys, so the server is storage — a Turbo binary cannot read them.
+//
+// Nothing is on by default: declare `turboCache()` in `vx.workspace.ts`
+// (the local store is the floor beneath it) and give it a URL and a token (options, or
+// Turbo's own environment variables and turbo.json's `remoteCache` so a
+// self-hosted setup carries over).
+// With neither the plugin DECLINES and the run stays local.
+//
+// Imports core only through the public `@vzn/vx` specifier.
+import { readFileSync, unlinkSync } from 'node:fs'
+import { unlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import {
+  definePlugin,
+  LayeredCache,
+  type CacheLayer,
+  type RemoteCacheLayer,
+  type VxPlugin,
+  refuseUnknownOptions,
+  type PluginOptionKinds,
+} from '@vzn/vx'
+import { deadlineNamed } from '../remote-deadline.js'
+import { withRetry } from '../remote-retry.js'
+import { headerValueFault } from '../remote-token.js'
+
+export interface TurboCacheOptions {
+  /** Base URL of the cache server (`https://cache.example.com`), or `TURBO_API`; with a token and neither, Vercel's hosted cache, as for `turbo`. */
+  apiUrl?: string
+  /** Bearer token every request carries, or `TURBO_TOKEN`. */
+  token?: string
+  /** `teamId` query parameter, or `TURBO_TEAMID`. Required with `signatureKey`. */
+  teamId?: string
+  /** `slug` query parameter (a team slug), or `TURBO_TEAM`. */
+  teamSlug?: string
+  /**
+   * Sign uploads and verify downloads with Turbo's artifact signature
+   * (HMAC-SHA256, `x-artifact-tag`), or `TURBO_REMOTE_CACHE_SIGNATURE_KEY`
+   * where turbo.json sets `remoteCache.signature: true`, as Turbo reads it.
+   * At least 32 bytes, used raw. A download whose tag does not verify is a
+   * miss, never a restore.
+   */
+  signatureKey?: string
+  /**
+   * Per-request deadline for HEAD/GET/POST, or `TURBO_REMOTE_CACHE_TIMEOUT`
+   * / turbo.json's `remoteCache.timeout` (whole seconds); default 30 s.
+   * 0 is no deadline, as in Turbo.
+   */
+  timeoutMs?: number
+  /** … and for PUT, or `TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT` / `remoteCache.uploadTimeout`; default 60 s. */
+  uploadTimeoutMs?: number
+  /** Resends of a request answered 429 / 5xx or never connected (default 1, Turbo's); 0 turns them off. */
+  retries?: number
+}
+
+/** turbo.json's `remoteCache` block: the source below Turbo's environment, as in Turbo. */
+export interface TurboJsonRemoteCache {
+  apiUrl?: unknown
+  signature?: unknown
+  teamId?: unknown
+  teamSlug?: unknown
+  enabled?: unknown
+  timeout?: unknown
+  uploadTimeout?: unknown
+}
+
+/** `.turbo/config.json`'s fields, under any of the spellings Turbo accepts. */
+export interface TurboLocalConfig {
+  apiUrl?: unknown
+  teamId?: unknown
+  teamSlug?: unknown
+  token?: unknown
+}
+
+export interface TurboCacheConfig {
+  apiUrl: string
+  token: string
+  teamId?: string
+  teamSlug?: string
+  signatureKey?: string
+  timeoutMs: number
+  uploadTimeoutMs: number
+  retries: number
+}
+
+/** Turbo's signature message prefix (`crates/turborepo-cache/src/signature_authentication.rs`). */
+const SIGNATURE_MESSAGE_PREFIX = 'artifact-signature:v2'
+export const MIN_SIGNATURE_KEY_LENGTH = 32
+
+// Bun's own hasher and the global `crypto`, not `node:crypto`: importing that
+// module cost every `@vzn/vx-migrate` user 6.6 ms at startup, remote cache
+// or not (G-121).
+function updateLength(mac: Bun.CryptoHasher, byteLength: number): void {
+  const len = Buffer.alloc(8)
+  len.writeBigUInt64LE(BigInt(byteLength))
+  mac.update(len)
+}
+
+/**
+ * `x-artifact-tag`: base64(HMAC-SHA256(key, fields)) where every field is
+ * prefixed with its byte length as a little-endian u64 — prefix, hash,
+ * team id, body — exactly as Turbo generates and verifies it. The body is
+ * read as a stream, so a file-backed Blob is signed without being held.
+ */
+export async function artifactTag(
+  key: Uint8Array,
+  hash: string,
+  teamId: string,
+  body: Blob,
+): Promise<string> {
+  const mac = new Bun.CryptoHasher('sha256', key)
+  for (const field of [
+    Buffer.from(SIGNATURE_MESSAGE_PREFIX),
+    Buffer.from(hash),
+    Buffer.from(teamId),
+  ]) {
+    updateLength(mac, field.byteLength)
+    mac.update(field)
+  }
+  updateLength(mac, body.size)
+  for await (const chunk of body.stream()) mac.update(chunk)
+  return mac.digest('base64')
+}
+
+/**
+ * The temps not yet removed. Core's signal exit is `process.exit`, which
+ * awaits nothing, so a Ctrl-C between the download and the last read left
+ * the artifact's temp behind (item 848); the process's `exit` event
+ * removes what is still listed.
+ */
+const liveTemps = new Set<string>()
+let exitHooked = false
+function trackTemp(file: string): void {
+  liveTemps.add(file)
+  if (exitHooked) return
+  exitHooked = true
+  process.on('exit', () => {
+    for (const f of liveTemps) {
+      try {
+        unlinkSync(f)
+      } catch {
+        // never written, or gone
+      }
+    }
+  })
+}
+
+async function removeTemp(file: string): Promise<void> {
+  // Listed until the unlink lands: an exit in between would otherwise find
+  // nothing to remove and leave the temp (item 868).
+  await unlink(file).catch(() => undefined)
+  liveTemps.delete(file)
+}
+
+/** The verified temp as a body that deletes the temp once read to the end or cancelled. */
+function unlinkingStream(file: string): ReadableStream<Uint8Array> {
+  const reader = Bun.file(file).stream().getReader()
+  const remove = () => removeTemp(file)
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await reader.read()
+        if (next.done) {
+          await remove()
+          controller.close()
+        } else {
+          controller.enqueue(next.value)
+        }
+      } catch (err) {
+        await remove()
+        controller.error(err)
+      }
+    },
+    async cancel(reason) {
+      await reader.cancel(reason)
+      await remove()
+    },
+  })
+}
+
+function tagsEqual(expected: string, actual: string): boolean {
+  const a = Buffer.from(expected, 'base64')
+  const b = Buffer.from(actual, 'base64')
+  if (a.byteLength !== b.byteLength) return false
+  // Constant time over the bytes, as timingSafeEqual is.
+  let diff = 0
+  for (let i = 0; i < a.byteLength; i++) diff |= a[i]! ^ b[i]!
+  return diff === 0
+}
+
+/** Where `turbo` itself sends a token with no `apiUrl`: Vercel's hosted Remote Cache. */
+export const VERCEL_API = 'https://vercel.com/api'
+
+/** Resolve options over Turbo's environment; `undefined` = not configured. */
+export function resolveTurboCacheConfig(
+  options: TurboCacheOptions,
+  env: Record<string, string | undefined> = Bun.env,
+  file: TurboJsonRemoteCache = {},
+  /** The repo's `.turbo/config.json` (`turbo link` writes it): below the environment, above turbo.json. */
+  local: TurboLocalConfig = {},
+): TurboCacheConfig | undefined {
+  // `enabled: false` turns Turbo's remote cache off whatever the env says;
+  // options name a cache for vx alone, and win.
+  if (file.enabled === false && options.apiUrl === undefined && options.token === undefined)
+    return undefined
+  const fromFile = (v: unknown): string | undefined => (typeof v === 'string' ? v : undefined)
+  // A Vercel build hands Turbo its cache as VERCEL_ARTIFACTS_TOKEN and
+  // _OWNER (the team id), taken where TURBO_TOKEN with a team is not set
+  // (Turbo's `override_env.rs`); unread, turboCache() declined on Vercel.
+  const turboPair = env['TURBO_TOKEN'] && (env['TURBO_TEAMID'] || env['TURBO_TEAM'])
+  const vercel =
+    !turboPair && env['VERCEL_ARTIFACTS_TOKEN'] && env['VERCEL_ARTIFACTS_OWNER']
+      ? { token: env['VERCEL_ARTIFACTS_TOKEN'], teamId: env['VERCEL_ARTIFACTS_OWNER'] }
+      : { token: undefined, teamId: turboPair ? undefined : env['VERCEL_ARTIFACTS_OWNER'] }
+  const token = options.token ?? env['TURBO_TOKEN'] ?? vercel.token ?? fromFile(local.token)
+  // Turbo's own default when a token is set and no `apiUrl` is: Vercel's
+  // hosted Remote Cache. A token alone is a configured cache, as it is for
+  // `turbo`; no token at all is the declined, local run.
+  const apiUrl = (
+    options.apiUrl ??
+    env['TURBO_API'] ??
+    fromFile(local.apiUrl) ??
+    fromFile(file.apiUrl) ??
+    (token ? VERCEL_API : undefined)
+  )?.replace(/\/+$/, '')
+  if (!apiUrl || !token) return undefined
+  // The URL is printed in every refusal line, so a `user:pass@` in it would
+  // leak to the log. Credentials go in the token.
+  if (URL.canParse(apiUrl)) {
+    const u = new URL(apiUrl)
+    if (u.username !== '' || u.password !== '')
+      throw new Error(
+        'vx/turbo-cache: apiUrl carries credentials (user:pass@); pass them as the token instead',
+      )
+  }
+  const fault = headerValueFault(token)
+  if (fault !== null)
+    throw new Error(
+      `vx/turbo-cache: the token holds ${fault}, which no HTTP header can carry — check the secret (it is not printed)`,
+    )
+  const teamId =
+    options.teamId ??
+    env['TURBO_TEAMID'] ??
+    vercel.teamId ??
+    fromFile(local.teamId) ??
+    fromFile(file.teamId)
+  const teamSlug =
+    options.teamSlug ?? env['TURBO_TEAM'] ?? fromFile(local.teamSlug) ?? fromFile(file.teamSlug)
+  // Turbo signs only under `remoteCache.signature: true`; the env key alone
+  // signs nothing there, and a short one here refused the whole cache.
+  // `TURBO_SIGNATURE` (1/true, 0/false) sits above turbo.json, as in Turbo.
+  const signEnv = env['TURBO_SIGNATURE']
+  let signing = file.signature === true
+  if (signEnv !== undefined && signEnv !== '') {
+    if (!/^(1|0|true|false)$/.test(signEnv))
+      throw new Error(
+        `vx/turbo-cache: TURBO_SIGNATURE should be 1 or 0, got ${JSON.stringify(signEnv)}`,
+      )
+    signing = signEnv === '1' || signEnv === 'true'
+  }
+  const signatureKey =
+    options.signatureKey ?? (signing ? env['TURBO_REMOTE_CACHE_SIGNATURE_KEY'] : undefined)
+  if (signatureKey !== undefined) {
+    if (Buffer.byteLength(signatureKey) < MIN_SIGNATURE_KEY_LENGTH) {
+      throw new Error(
+        `vx/turbo-cache: signatureKey must be at least ${MIN_SIGNATURE_KEY_LENGTH} bytes (Turbo's minimum)`,
+      )
+    }
+    if (!teamId)
+      throw new Error(
+        'vx/turbo-cache: signatureKey needs teamId — the team id is part of the signed message',
+      )
+  }
+  const retries = options.retries ?? 1
+  // A NaN never reaches the bound, and the request would be resent forever.
+  if (!Number.isInteger(retries) || retries < 0)
+    throw new Error(`vx/turbo-cache: retries must be a whole number ≥ 0, got ${retries}`)
+  // 0 is no deadline, as Turbo reads it; a negative or non-number one made
+  // AbortSignal.timeout throw on every request.
+  for (const name of ['timeoutMs', 'uploadTimeoutMs'] as const) {
+    const ms = options[name]
+    if (ms !== undefined && !(typeof ms === 'number' && Number.isFinite(ms) && ms >= 0))
+      throw new Error(`vx/turbo-cache: ${name} must be ms ≥ 0 (0: none), got ${JSON.stringify(ms)}`)
+  }
+  return {
+    apiUrl,
+    token,
+    ...(teamId ? { teamId } : {}),
+    ...(teamSlug ? { teamSlug } : {}),
+    ...(signatureKey !== undefined ? { signatureKey } : {}),
+    timeoutMs:
+      options.timeoutMs ??
+      seconds(env['TURBO_REMOTE_CACHE_TIMEOUT'], 'TURBO_REMOTE_CACHE_TIMEOUT') ??
+      seconds(file.timeout, 'remoteCache.timeout') ??
+      30_000,
+    uploadTimeoutMs:
+      options.uploadTimeoutMs ??
+      seconds(env['TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT'], 'TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT') ??
+      seconds(file.uploadTimeout, 'remoteCache.uploadTimeout') ??
+      60_000,
+    retries,
+  }
+}
+
+/**
+ * Turbo's timeout, whole seconds, as ms; `undefined` when unset. A value
+ * Turbo would refuse is refused here rather than read as some other wait.
+ */
+function seconds(v: unknown, name: string): number | undefined {
+  if (v === undefined || v === null || v === '') return undefined
+  const n = typeof v === 'string' ? Number(v) : v
+  if (typeof n !== 'number' || !Number.isInteger(n) || n < 0)
+    throw new Error(`vx/turbo-cache: ${name} must be whole seconds ≥ 0, got ${JSON.stringify(v)}`)
+  return n * 1000
+}
+
+/** A response's text, or null (the rest cancelled) once it passes `max` bytes. */
+async function boundedText(res: Response, max: number): Promise<string | null> {
+  if (Number(res.headers.get('content-length') ?? 0) > max) {
+    await res.body?.cancel()
+    return null
+  }
+  const reader = res.body?.getReader()
+  if (reader === undefined) return ''
+  const parts: Uint8Array[] = []
+  let n = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    n += value.byteLength
+    if (n > max) {
+      await reader.cancel()
+      return null
+    }
+    parts.push(value)
+  }
+  return Buffer.concat(parts).toString('utf8')
+}
+
+/**
+ * A signed body is written whole before its tag can be checked, so a
+ * server that never ended one filled the temp's disk (L-8). Core refuses
+ * an artifact past its 2 GiB ceiling (zstd's bound on it here) anyway, so
+ * nothing larger is ever worth keeping.
+ */
+const MAX_SIGNED_BODY = 2 * 1024 ** 3 + ((2 * 1024 ** 3) >> 8) + 64 * 1024
+
+/**
+ * The seam implementation: `has` is HEAD, `hasMany` is the batch query,
+ * `get`/`put` carry `x-artifact-duration` (and the tag when signing). An
+ * auth failure (401/403) throws ONCE — LayeredCache reports it — and then
+ * turns the layer off for the rest of the process, so a bad token costs one
+ * line, not one per task — the requests already in flight when it lands
+ * degrade in silence rather than repeating it.
+ *
+ * Bodies stream both ways: `put` sends the Blob core hands it, `get`
+ * returns the `fetch` Response. With a signature key the tag must verify
+ * before core sees a byte, so a signed download lands in a temp under
+ * `tempDir` first and is handed over only once it has.
+ */
+export class TurboRemoteCache implements RemoteCacheLayer {
+  private disabled = false
+  private readonly key: Uint8Array | undefined
+  readonly endpoint: string
+  constructor(
+    private readonly config: TurboCacheConfig,
+    private readonly fetchImpl: typeof fetch = fetch,
+    private readonly tempDir: string = tmpdir(),
+    private readonly wait: (ms: number) => Promise<void> = Bun.sleep,
+    /** The most a signed body may hold before its tag is checked (a test lowers it). */
+    private readonly maxSignedBody: number = MAX_SIGNED_BODY,
+  ) {
+    this.key = config.signatureKey === undefined ? undefined : Buffer.from(config.signatureKey)
+    this.endpoint = `${config.apiUrl}/v8/artifacts`
+  }
+
+  private url(pathname: string): string {
+    const u = new URL(`${this.config.apiUrl}/v8/artifacts${pathname}`)
+    // Turbo sends a team id only in Vercel's `team_` form (its API client's
+    // `add_team_params`); a personal account's owner id is not one, and the
+    // signature, which folds the id as given, is unaffected.
+    if (this.config.teamId?.startsWith('team_')) u.searchParams.set('teamId', this.config.teamId)
+    if (this.config.teamSlug) u.searchParams.set('slug', this.config.teamSlug)
+    return u.toString()
+  }
+
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.config.token}`,
+      'x-artifact-client-interactive': process.stdout.isTTY ? '1' : '0',
+      ...extra,
+    }
+  }
+
+  /**
+   * `undefined` = the token was refused and the refusal is ALREADY
+   * reported, so the caller degrades to its miss value in silence. Only the
+   * first refusal throws, and a run's calls are concurrent: six projects
+   * under a bad token printed five identical lines before this (2026-09-20).
+   */
+  private async request(
+    method: string,
+    pathname: string,
+    init: { body?: Blob | string; headers?: Record<string, string>; timeoutMs?: number } = {},
+  ): Promise<Response | undefined> {
+    const timeoutMs = init.timeoutMs ?? this.config.timeoutMs
+    const res = await withRetry(
+      () =>
+        this.fetchImpl(this.url(pathname), {
+          method,
+          headers: this.headers(init.headers),
+          ...(init.body === undefined ? {} : { body: init.body }),
+          // 0 is Turbo's "no deadline".
+          ...(timeoutMs === 0 ? {} : { signal: AbortSignal.timeout(timeoutMs) }),
+        }),
+      this.config.retries,
+      this.wait,
+    ).catch((err: unknown) => {
+      throw deadlineNamed(err, timeoutMs)
+    })
+    if (res.status === 401 || res.status === 403) {
+      const first = !this.disabled
+      this.disabled = true
+      if (!first) return undefined
+      throw new Error(`HTTP ${res.status}: the token was refused; remote cache off for this run`)
+    }
+    return res
+  }
+
+  async has(hash: string): Promise<boolean> {
+    if (this.disabled) return false
+    const res = await this.request('HEAD', `/${hash}`)
+    if (res === undefined) return false
+    if (res.status === 200) return true
+    if (res.status === 404) return false
+    throw new Error(`HTTP ${res.status}`)
+  }
+
+  async hasMany(hashes: readonly string[]): Promise<Set<string> | null> {
+    if (this.disabled || hashes.length === 0) return this.disabled ? new Set() : null
+    const res = await this.request('POST', '', {
+      body: JSON.stringify({ hashes }),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    if (res === undefined) return new Set()
+    if (res.status !== 200) return null
+    // An answer per hash is a few hundred bytes of ArtifactInfo; a reply
+    // past this bound is no answer, read no further than the bound (L-9).
+    const bound = hashes.length * 4096 + 64 * 1024
+    const text = await boundedText(res, bound)
+    if (text === null) return null
+    const info = JSON.parse(text) as Record<string, unknown>
+    // Each hash answers ArtifactInfo, null, or `{ error: { message } }`; an
+    // error entry is not a stored artifact, and it was counted as one (a GET
+    // spent on a 404, item 929).
+    return new Set(
+      hashes.filter((h) => {
+        const v = info[h]
+        return typeof v === 'object' && v !== null && !('error' in v)
+      }),
+    )
+  }
+
+  async get(hash: string): Promise<{ body: Response; durationMs: number | undefined } | null> {
+    if (this.disabled) return null
+    // A gateway that keys binary media on Accept base64-encodes a `*/*`
+    // response, and every hit read as a corrupt artifact (nx#33092's class).
+    const res = await this.request('GET', `/${hash}`, {
+      headers: { Accept: 'application/octet-stream' },
+    })
+    if (res === undefined) return null
+    if (res.status === 404) return null
+    if (res.status !== 200) throw new Error(`HTTP ${res.status}`)
+    const duration = Number(res.headers.get('x-artifact-duration'))
+    const durationMs = Number.isFinite(duration) && duration > 0 ? duration : undefined
+    if (this.key === undefined) return { body: res, durationMs }
+    return { body: await this.verified(this.key, hash, res), durationMs }
+  }
+
+  /**
+   * The tag's message carries the body's length BEFORE its bytes, and a
+   * chunked response declares no length, so the body is written to the temp
+   * first and signed from there: two passes over a file, never one in memory.
+   */
+  private async verified(key: Uint8Array, hash: string, res: Response): Promise<Response> {
+    const refused = () => new Error('the artifact signature did not verify — treated as a miss')
+    const tag = res.headers.get('x-artifact-tag')
+    if (tag === null) {
+      await res.body?.cancel()
+      throw refused()
+    }
+    const temp = path.join(this.tempDir, `vx-turbo-${hash}-${crypto.randomUUID()}`)
+    trackTemp(temp)
+    try {
+      const max = this.maxSignedBody
+      const past = () => new Error(`the signed artifact runs past ${max} bytes — treated as a miss`)
+      if (Number(res.headers.get('content-length') ?? 0) > max) throw past()
+      let n = 0
+      const counted = res.body?.pipeThrough(
+        new TransformStream<Uint8Array, Uint8Array>({
+          transform(chunk, controller) {
+            n += chunk.byteLength
+            if (n > max) controller.error(past())
+            else controller.enqueue(chunk)
+          },
+        }),
+      )
+      await Bun.write(temp, new Response(counted ?? null))
+      const expected = await artifactTag(key, hash, this.config.teamId ?? '', Bun.file(temp))
+      if (!tagsEqual(expected, tag)) throw refused()
+    } catch (err) {
+      await removeTemp(temp)
+      throw err
+    }
+    return new Response(unlinkingStream(temp))
+  }
+
+  async put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void> {
+    if (this.disabled) return
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/octet-stream',
+      'Content-Length': String(body.size),
+      'x-artifact-duration': String(Math.max(0, Math.round(meta.durationMs))),
+    }
+    if (this.key !== undefined) {
+      headers['x-artifact-tag'] = await artifactTag(this.key, hash, this.config.teamId ?? '', body)
+    }
+    const res = await this.request('PUT', `/${hash}`, {
+      body,
+      headers,
+      timeoutMs: this.config.uploadTimeoutMs,
+    })
+    if (res === undefined) return
+    if (res.status !== 200 && res.status !== 202) throw new Error(`HTTP ${res.status}`)
+  }
+}
+
+/**
+ * What Turbo's own switches leave of the remote cache: `TURBO_CACHE`
+ * (`--cache`'s syntax, where an omitted source is off) and
+ * `TURBO_REMOTE_CACHE_READ_ONLY`. A CI that sets either for an untrusted
+ * pull request kept Turbo from writing the shared cache and not vx. They
+ * only narrow what `--cache` allows, never widen it.
+ */
+export function turboRemoteAccess(env: Record<string, string | undefined>): {
+  read: boolean
+  write: boolean
+} {
+  let read = true
+  let write = true
+  const spec = env['TURBO_CACHE']
+  if (spec !== undefined && spec !== '') {
+    read = write = false
+    for (const part of spec.split(',')) {
+      const m = /^(local|remote):([rw]*)$/.exec(part.trim())
+      if (m === null)
+        throw new Error(
+          `vx/turbo-cache: TURBO_CACHE ${JSON.stringify(spec)} is not --cache's syntax (e.g. local:rw,remote:r)`,
+        )
+      if (m[1] !== 'remote') continue
+      read = m[2]!.includes('r')
+      write = m[2]!.includes('w')
+    }
+  }
+  if (/^(1|true)$/i.test(env['TURBO_REMOTE_CACHE_READ_ONLY'] ?? '')) write = false
+  return { read, write }
+}
+
+/**
+ * The repo's `.turbo/config.json`, by Turbo's field names and their
+ * aliases (`apiurl`, `ApiUrl`, `APIURL`, …); `{}` when absent or unreadable.
+ */
+function localConfigOf(root: string): TurboLocalConfig {
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(path.join(root, '.turbo', 'config.json'), 'utf8'))
+  } catch {
+    return {}
+  }
+  if (typeof raw !== 'object' || raw === null) return {}
+  const byLower = new Map(Object.entries(raw).map(([k, v]) => [k.toLowerCase(), v]))
+  return {
+    apiUrl: byLower.get('apiurl'),
+    teamId: byLower.get('teamid'),
+    teamSlug: byLower.get('teamslug'),
+    token: byLower.get('token'),
+  }
+}
+
+/** The root turbo.json's (or turbo.jsonc's) `remoteCache`; `{}` when there is none or it does not parse. */
+function remoteCacheOf(root: string): TurboJsonRemoteCache {
+  for (const name of ['turbo.json', 'turbo.jsonc']) {
+    let text: string
+    try {
+      text = readFileSync(path.join(root, name), 'utf8')
+    } catch {
+      continue
+    }
+    try {
+      const rc = (Bun.JSONC.parse(text) as { remoteCache?: unknown } | null)?.remoteCache
+      return typeof rc === 'object' && rc !== null ? (rc as TurboJsonRemoteCache) : {}
+    } catch {
+      return {}
+    }
+  }
+  return {}
+}
+
+/** Each option `TurboCacheOptions` names, with its kind: derived from the type, so the two cannot drift. */
+const TURBO_CACHE_KEYS: PluginOptionKinds<TurboCacheOptions> = {
+  apiUrl: 'string',
+  token: 'string',
+  teamId: 'string',
+  teamSlug: 'string',
+  signatureKey: 'string',
+  timeoutMs: 'number',
+  uploadTimeoutMs: 'number',
+  retries: 'number',
+}
+
+/**
+ * Declare in `vx.workspace.ts`; the local store stays the floor beneath it:
+ *
+ * ```ts
+ * plugins: [turboCache({ apiUrl: 'https://cache.example.com', token: process.env.CACHE_TOKEN })]
+ * ```
+ *
+ * Declines without a URL and a token, so it is safe to leave declared.
+ */
+export function turboCache(options: TurboCacheOptions = {}): VxPlugin {
+  refuseUnknownOptions('turboCache()', options, TURBO_CACHE_KEYS)
+  return definePlugin(import.meta, {
+    cache(ctx): CacheLayer | undefined {
+      const config = resolveTurboCacheConfig(
+        options,
+        Bun.env,
+        remoteCacheOf(ctx.workspaceRoot),
+        localConfigOf(ctx.workspaceRoot),
+      )
+      if (config === undefined) return undefined
+      const remote = turboRemoteAccess(Bun.env)
+      const policy = {
+        ...ctx.policy,
+        remoteRead: ctx.policy.remoteRead && remote.read,
+        remoteWrite: ctx.policy.remoteWrite && remote.write,
+      }
+      if (!policy.remoteRead && !policy.remoteWrite) return undefined
+      // A signed download waits in a temp until its tag checks: in vx's
+      // cache directory, which the sandbox walls, not the shared temp dir a
+      // sandboxed task may read (L-45).
+      return new LayeredCache(ctx.localCache, new TurboRemoteCache(config, fetch, ctx.cacheDir), {
+        policy,
+        onRemoteError: (err) => ctx.warn(`vx/turbo-cache: ${err.message}`),
+      })
+    },
+  })
+}