@vzn/vx 0.0.12 → 0.0.15

package/src/cache/remote-cache.ts

@@ -1,251 +0,0 @@
-// Remote cache HTTP client — speaks the Turborepo /v8/artifacts/ spec.
-//
-// Wire-level only. Knows nothing about local storage, tar formats, or
-// how the orchestrator uses the cache; those concerns live in the
-// LayeredCache. Three operations — GET (read), PUT (write), and HEAD
-// (existence probe for the plan path).
-//
-// Reference servers we want to interop with at the HTTP layer:
-//   ducktors/turborepo-remote-cache, Fox32/openturbo-remote-cache,
-//   Vercel hosted cache.
-
-import { createHmac, timingSafeEqual } from 'node:crypto'
-
-export interface RemoteCacheConfig {
-  /** Base URL of the cache server, e.g. https://cache.example.com */
-  baseUrl: string
-  /** Bearer token sent as `Authorization: Bearer <token>`. */
-  token: string
-  /** Optional Turbo-style tenant identifiers; sent as ?teamId=&slug=. */
-  teamId?: string
-  slug?: string
-  /** Per-request timeout in ms. Default 60_000. */
-  timeoutMs?: number
-  /**
-   * HMAC artifact-signing key (Turbo's `remoteCache.signature` scheme).
-   * When set, every PUT carries an `x-artifact-tag` over the artifact
-   * and every GET response must carry a matching tag — a missing or
-   * mismatched tag is a `RemoteCacheError`, never a silent accept.
-   */
-  signatureKey?: string
-  /**
-   * Untrusted per-PR partition id, sent as `x-vx-cache-scope`. A compatible
-   * remote-cache server MAY partition untrusted writes by this id so one fork
-   * PR can't read or poison another's cache. Ignored by trusted writes and by
-   * third-party Turbo servers.
-   */
-  cacheScope?: string
-}
-
-export interface RemotePutMetadata {
-  /** Task duration in ms. Sent as x-artifact-duration. */
-  durationMs: number
-}
-
-export interface RemoteGetResult {
-  body: ArrayBuffer
-  durationMs: number | undefined
-}
-
-/**
- * Hard cap on a downloaded artifact body (compressed bytes). A malicious or
- * compromised remote (or a MITM answering a GET) must not be able to stream an
- * unbounded body into `res.arrayBuffer()` and exhaust the victim's memory —
- * the download aborts past this and degrades to a cache miss. Mirrors the
- * server-side PUT cap.
- */
-export const MAX_REMOTE_ARTIFACT_BYTES = 512 * 1024 * 1024
-
-/**
- * Read a response body, aborting once cumulative bytes exceed `max`. Streams
- * via the body reader so a lying (or absent) content-length can't defeat the
- * cap. Falls back to `arrayBuffer()` only when the body isn't a stream.
- *
- * Exported for tests: the `max` param lets a unit test exercise the
- * mid-stream abort with a tiny cap instead of a 512 MiB body.
- */
-export async function readBodyBounded(res: Response, max: number): Promise<ArrayBuffer> {
-  const reader = res.body?.getReader()
-  if (reader === undefined) return await res.arrayBuffer()
-  const chunks: Uint8Array[] = []
-  let total = 0
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) break
-    if (value === undefined) continue
-    total += value.byteLength
-    if (total > max) {
-      await reader.cancel().catch(() => {})
-      throw new Error(`artifact exceeds ${max}-byte download cap`)
-    }
-    chunks.push(value)
-  }
-  const out = new Uint8Array(total)
-  let off = 0
-  for (const c of chunks) {
-    out.set(c, off)
-    off += c.byteLength
-  }
-  return out.buffer
-}
-
-export class RemoteCache {
-  constructor(private readonly config: RemoteCacheConfig) {}
-
-  async get(hash: string): Promise<RemoteGetResult | null> {
-    const res = await this.fetch('GET', this.artifactUrl(hash))
-    if (res.status === 404) return null
-    if (!res.ok) throw new RemoteCacheError(`GET ${hash} → ${res.status}`, res.status)
-    // Refuse an honestly-declared oversize body before reading a byte.
-    const declaredLen = Number(res.headers.get('content-length') ?? '')
-    if (Number.isFinite(declaredLen) && declaredLen > MAX_REMOTE_ARTIFACT_BYTES) {
-      throw new RemoteCacheError(
-        `GET ${hash} → artifact too large (${declaredLen} bytes > ${MAX_REMOTE_ARTIFACT_BYTES} cap)`,
-        res.status,
-      )
-    }
-    // A body that ends before the declared content-length (server died
-    // mid-transfer) throws from the reader, not from fetch() — wrap it here
-    // so callers see a typed RemoteCacheError and the layered cache can
-    // degrade it to a miss. The bounded read also aborts a body that lies
-    // about (or omits) its length once it crosses the cap.
-    let body: ArrayBuffer
-    try {
-      body = await readBodyBounded(res, MAX_REMOTE_ARTIFACT_BYTES)
-    } catch (err) {
-      throw new RemoteCacheError(
-        `GET ${hash} → body read failed: ${(err as Error).message}`,
-        res.status,
-        err,
-      )
-    }
-    if (this.config.signatureKey !== undefined) {
-      const received = res.headers.get('x-artifact-tag')
-      if (received === null) {
-        // A signing deployment must not silently accept unsigned
-        // artifacts — that would let an attacker strip the tag.
-        throw new RemoteCacheError(
-          `GET ${hash} → signature verification enabled but response carries no x-artifact-tag`,
-          res.status,
-        )
-      }
-      if (!this.tagMatches(hash, new Uint8Array(body), received)) {
-        throw new RemoteCacheError(`GET ${hash} → x-artifact-tag signature mismatch`, res.status)
-      }
-    }
-    return {
-      body,
-      durationMs: parseIntHeader(res.headers.get('x-artifact-duration')),
-    }
-  }
-
-  /**
-   * Existence probe — Turbo wire `HEAD /v8/artifacts/:hash` (200 =
-   * exists, 404 = not). No body transfer; the plan path (`--dry` /
-   * `--graph`) predicts remote hits with this so it never downloads
-   * artifacts. Other failures throw a `RemoteCacheError` like `get`;
-   * the LayeredCache degrades them to a miss.
-   */
-  async has(hash: string): Promise<boolean> {
-    const res = await this.fetch('HEAD', this.artifactUrl(hash))
-    if (res.status === 404) return false
-    if (!res.ok) throw new RemoteCacheError(`HEAD ${hash} → ${res.status}`, res.status)
-    return true
-  }
-
-  async put(hash: string, body: ArrayBuffer | Uint8Array, meta: RemotePutMetadata): Promise<void> {
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/octet-stream',
-      'Content-Length': String(body.byteLength),
-      'x-artifact-duration': String(meta.durationMs),
-    }
-    if (this.config.signatureKey !== undefined) {
-      headers['x-artifact-tag'] = this.artifactTag(
-        hash,
-        body instanceof Uint8Array ? body : new Uint8Array(body),
-      )
-    }
-
-    const res = await this.fetch('PUT', this.artifactUrl(hash), { body, headers })
-    // Any 2xx is success — Turbo-compatible servers answer 200/201/202.
-    if (!res.ok) {
-      throw new RemoteCacheError(`PUT ${hash} → ${res.status}`, res.status)
-    }
-  }
-
-  // Turbo's construction (crates/turborepo-cache/src/signature_authentication.rs):
-  // base64(HMAC-SHA256(key, utf8(hash) || utf8(teamId ?? '') || body)).
-  // Byte-compatible with Turbo so signing servers/clients interop.
-  private artifactTag(hash: string, body: Uint8Array): string {
-    return createHmac('sha256', this.config.signatureKey!)
-      .update(hash)
-      .update(this.config.teamId ?? '')
-      .update(body)
-      .digest('base64')
-  }
-
-  private tagMatches(hash: string, body: Uint8Array, received: string): boolean {
-    const expected = Buffer.from(this.artifactTag(hash, body), 'base64')
-    const actual = Buffer.from(received, 'base64')
-    return expected.length === actual.length && timingSafeEqual(expected, actual)
-  }
-
-  private artifactUrl(hash: string): string {
-    return this.urlWithTenancy(`${this.config.baseUrl}/v8/artifacts/${encodeURIComponent(hash)}`)
-  }
-
-  private urlWithTenancy(base: string): string {
-    const params = new URLSearchParams()
-    if (this.config.teamId) params.set('teamId', this.config.teamId)
-    if (this.config.slug) params.set('slug', this.config.slug)
-    const q = params.toString()
-    return q ? `${base}?${q}` : base
-  }
-
-  private async fetch(
-    method: string,
-    url: string,
-    init?: { body?: ArrayBuffer | Uint8Array | string; headers?: Record<string, string> },
-  ): Promise<Response> {
-    const timeoutMs = this.config.timeoutMs ?? 60_000
-    try {
-      return await fetch(url, {
-        method,
-        signal: AbortSignal.timeout(timeoutMs),
-        headers: {
-          Authorization: `Bearer ${this.config.token}`,
-          // The untrusted per-PR partition (an optional server-side extension;
-          // a third-party Turbo server ignores it). Isolates one fork PR's
-          // writes/reads from another's within the untrusted tier.
-          ...(this.config.cacheScope !== undefined
-            ? { 'x-vx-cache-scope': this.config.cacheScope }
-            : {}),
-          ...init?.headers,
-        },
-        ...(init?.body !== undefined ? { body: init.body } : {}),
-      })
-    } catch (err) {
-      if (err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError')) {
-        throw new RemoteCacheError(`${method} ${url} timed out after ${timeoutMs}ms`, 0, err)
-      }
-      throw new RemoteCacheError(`${method} ${url} failed: ${(err as Error).message}`, 0, err)
-    }
-  }
-}
-
-export class RemoteCacheError extends Error {
-  constructor(
-    message: string,
-    public readonly status: number,
-    public override readonly cause?: unknown,
-  ) {
-    super(message)
-    this.name = 'RemoteCacheError'
-  }
-}
-
-function parseIntHeader(v: string | null): number | undefined {
-  if (v === null) return undefined
-  const n = Number(v)
-  return Number.isFinite(n) ? n : undefined
-}

package/src/orchestrator/remote-cache-setup.ts

@@ -1,60 +0,0 @@
-import {
-  Cache,
-  type CacheLayer,
-  type CachePolicy,
-  FULL_CACHE_POLICY,
-  LayeredCache,
-  RemoteCache,
-} from '../cache/index.js'
-import type { Logger } from './logger.js'
-import { resolveCacheScope } from './run-context.js'
-
-/**
- * Wrap the local cache in a `LayeredCache` when a remote cache is configured
- * via `VX_REMOTE_CACHE_URL` + a token. This is the escape hatch for a
- * THIRD-PARTY, Turbo-compatible cache server. A `cache` plugin can provide a
- * remote cache INTERNALLY instead, in which case this env path isn't
- * needed.
- *
- * **Trust tier follows the token you present** — the server derives
- * trusted/untrusted from the bearer, so the client just presents whichever
- * token it has: `VX_REMOTE_CACHE_TOKEN` for a trusted context, or
- * `VX_REMOTE_CACHE_PR_TOKEN` for a fork PR (reads the trusted cache, writes
- * only the untrusted scope). A fork-PR CI job simply doesn't hold the trusted
- * secret, so "which token you have" IS the tier — no separate trust flag.
- *
- * Optional env: `VX_REMOTE_CACHE_TEAM_ID`, `VX_REMOTE_CACHE_SLUG`
- * (Turbo tenancy query params), `VX_REMOTE_CACHE_TIMEOUT_MS`,
- * `VX_REMOTE_CACHE_SIGNATURE_KEY` (HMAC artifact signing).
- */
-export function wrapWithRemoteCache(
-  local: Cache,
-  log: Logger,
-  policy: CachePolicy = FULL_CACHE_POLICY,
-): CacheLayer {
-  const url = process.env.VX_REMOTE_CACHE_URL
-  const token = process.env.VX_REMOTE_CACHE_TOKEN ?? process.env.VX_REMOTE_CACHE_PR_TOKEN
-  if (!url || !token) return local
-
-  const config: ConstructorParameters<typeof RemoteCache>[0] = { baseUrl: url, token }
-  const teamId = process.env.VX_REMOTE_CACHE_TEAM_ID
-  if (teamId) config.teamId = teamId
-  const slug = process.env.VX_REMOTE_CACHE_SLUG
-  if (slug) config.slug = slug
-  const timeoutMs = process.env.VX_REMOTE_CACHE_TIMEOUT_MS
-  if (timeoutMs) {
-    const n = Number(timeoutMs)
-    if (Number.isFinite(n) && n > 0) config.timeoutMs = n
-  }
-  const signatureKey = process.env.VX_REMOTE_CACHE_SIGNATURE_KEY
-  if (signatureKey) config.signatureKey = signatureKey
-  // Untrusted per-PR isolation: a fork PR's writes land in its own sub-scope.
-  const cacheScope = resolveCacheScope(process.env)
-  if (cacheScope) config.cacheScope = cacheScope
-
-  log.status(`remote cache: ${url}`)
-  return new LayeredCache(local, new RemoteCache(config), {
-    onRemoteError: (err) => log.status(`[vx] remote cache: ${err.message}`),
-    policy,
-  })
-}