@vzn/vx-cache-server 0.0.0 → 0.0.649

package/Dockerfile

@@ -0,0 +1,20 @@
+# vx-cache-server as a container, built from the repo root:
+#   docker build -f packages/vx-cache-server/Dockerfile -t vx-cache-server .
+#   docker run -p 8080:8080 -e ALLOW='https://token.actions.githubusercontent.com:acme/app:ci.yml' -e S3_BUCKET=… -e S3_ENDPOINT=… vx-cache-server
+# One bundled file: the server and the CI token check it shares with
+# vx's other servers (@vzn/vx-devtools), with jose.
+FROM oven/bun:1.4.4-slim@sha256:1846adf22496bd711036aae8be147e57bdebbaea2e5264e3e0b5af1db187d9a4 AS build
+WORKDIR /repo
+COPY packages/vx-devtools/package.json packages/vx-devtools/
+# jose as @vzn/vx-devtools pins it: the image names no version of its own.
+RUN cd packages/vx-devtools && bun install --production --ignore-scripts
+COPY packages/vx-devtools/src packages/vx-devtools/src/
+COPY packages/vx-cache-server/src packages/vx-cache-server/src/
+RUN mkdir -p node_modules/@vzn && ln -s ../../packages/vx-devtools node_modules/@vzn/vx-devtools \
+ && bun build packages/vx-cache-server/src/bun.ts --target=bun --outfile=/out/vx-cache-server.js
+
+FROM oven/bun:1.4.4-slim@sha256:1846adf22496bd711036aae8be147e57bdebbaea2e5264e3e0b5af1db187d9a4
+COPY --from=build /out/vx-cache-server.js /app/
+USER bun
+EXPOSE 8080
+ENTRYPOINT ["bun", "--no-env-file", "--no-install", "/app/vx-cache-server.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VZN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,151 @@
+# vx-cache protocol, v1
+
+An HTTP API for task artifacts. `@vzn/vx-cache-server` speaks it on Bun
+and on Cloudflare Workers; any server that does can take its place.
+Every route sits under `/v1`: a later version gets its own prefix, and a
+server may serve both.
+
+Turbo's routes (`/v8/artifacts`), under `/v1`:
+
+| Route                       | What it does                             |
+| --------------------------- | ---------------------------------------- |
+| `GET /v1/artifacts/<hash>`  | one artifact's bytes                     |
+| `HEAD /v1/artifacts/<hash>` | whether it is held, and its size         |
+| `PUT /v1/artifacts/<hash>`  | one artifact's bytes                     |
+| `POST /v1/artifacts`        | which of many hashes are held, and sizes |
+| `GET /v1/capabilities`      | the server's limits                      |
+
+Where it differs from Turbo: a read names its scopes (§ Keys), since an
+artifact lives in its branch's scope; every request names its issuer
+and repository by their hashes (§ Repository), so `teamId` and `slug`
+are refused; there is no events route.
+
+## Opaque strings
+
+The server never reads a hash or an artifact's bytes. It only stores
+them and compares hashes for equality, so a client may send them
+encrypted (a keyed hash for names, a cipher for bytes). No ref goes on
+the wire plain: a scope is its ref's hash (§ Keys), and the server
+hashes the token's ref the same way to find where a write goes.
+
+## Repository
+
+Every request names its repository: `vx-issuer`, the hash (§ Keys) of
+the CI issuer's URL as its tokens name it, no trailing slash
+(`https://token.actions.githubusercontent.com`), and `vx-repository`,
+the hash of its `org/name` there, lowercased. One missing or not a hash
+is `400`. A token of another repository than the one named is `403`.
+
+A server whose `READ_ACCESS` is `public` takes a request with no token
+too: it reads a repository its rules name (another is `403`) and writes
+nothing (`403`, `this request reads only`). Any other server answers a
+request with no token `401`.
+
+## Tokens
+
+A request's `Authorization: Bearer <token>` is a CI job's OIDC token
+(GitHub Actions, GitLab CI): there is no other. Its signature,
+`RS256`, `exp` and `aud` (the server's own) are checked, and the token
+alone decides what it reads and where it writes, by the server's
+`ALLOW` (`issuer:owner/repo:workflow` entries):
+
+- Its issuer and repository name (`repository` on GitHub, `project_path`
+  on GitLab, `org/name`, any case) are the repository it reads and writes; one `ALLOW`
+  does not name is `403`, and so is a job of a workflow it does not name
+  (`job_workflow_ref`, GitLab's `ci_config_ref_uri`). A repository's artifacts are never another's.
+- It writes its own ref's scope: on GitHub a `pull_request` run its merge
+  ref (`refs/pull/<n>/merge`), never its `head_ref`, which a fork names
+  and no claim tells from the repository's own; a merge queue's (`merge_group`) run
+  (`refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>`, that exact form)
+  its base branch (`refs/heads/<base>`), which its code is about to
+  become, else its `ref`; on GitLab its `ref_path`.
+- A `pull_request_target`, `issue_comment` or `workflow_run` run writes
+  nothing (a write is `403`): its `ref` is the base while it may run a
+  pull request's code. Nor does a GitLab `merge_request_event` pipeline unless its
+  `source_project_path` (GitLab 19.5+) names its own project: a fork's
+  runs in the parent project with the fork's branch as its `ref_path`.
+
+A bad token is `401`. A server with `ALLOW` empty does not start; a
+Worker, which cannot refuse to, refuses every request: `401`,
+`ALLOW is empty: set it to the CI workflows this server serves`. A server that
+cannot fetch the issuer's keys, or reads a broken key set (none, or two
+keys for one `kid`), answers `502`: the token is not refused,
+so a client keeps the remote for its next request.
+
+## Keys
+
+An artifact lives in one scope, and a key names both: `{ scope, hash }`.
+`scope` is a ref's hash: the first 128 bits of the SHA-256 of its UTF-8
+(`refs/heads/main`), 32 lowercase hex digits; a plain ref is `400`.
+`GET` and `HEAD` name one scope in `vx-scope`; a check names
+its scopes in its body.
+`hash` is 1 to 128 hex digits. A read is exact: the server answers the scope named and no
+other, so a client that wants its branch's work and then main's asks
+for both. Every read names a scope.
+
+An artifact is immutable. A server may expire one at any time: a
+download after a check that held it may miss, which a client reads as a
+miss.
+
+`GET /v1/artifacts/<hash>` (as Turbo's `GET /v8/artifacts/<hash>`) with
+`vx-scope: <scope>`: `200` with the bytes (`application/octet-stream`,
+`Cache-Control: private, max-age=31536000, immutable`: the bytes under a
+key never change), or `404`. `HEAD` is the same with no bytes, and names
+the size as `Content-Length`. A download may come chunked with no
+`Content-Length` (Bun.serve sends any streamed answer so), so a body cut
+short can end as cleanly as a whole one: a client checks the bytes
+themselves (vx refuses an artifact whose zstd frame, tar end or recorded
+key is missing) and reads one that fails as a miss.
+
+`POST /v1/artifacts` (Turbo's batch query) with `{ "hashes": [<hash>,
+…], "scopes": [<scope>, …] }`, the scopes in the order to read them, up
+to `maxCheckHashes` lookups (hashes × scopes): `{ "<hash>": { "size":
+<bytes>, "scope": <scope> } | null, … }`, one per hash, naming the first
+scope asked that holds it, which its download names. Each lookup is
+exact, and its time does not grow with what a scope holds. Every
+`/v1/artifacts` answer, a refusal too, names the server's limits, which
+a client chunks its checks by, sending the chunks at once:
+
+```
+vx-max-check-hashes: 500
+vx-max-upload-bytes: 100000000
+```
+
+`PUT /v1/artifacts/<hash>` (a token that writes, as Turbo's
+`PUT /v8/artifacts/<hash>`), with `Content-Length`: the body is the
+artifact's bytes, stored in the token's scope. One the scope already
+holds keeps its bytes, answered before they are read. `204`; past
+`maxUploadBytes`, `413`. A client may `check` first to skip what is
+held.
+
+Downloads and uploads go one artifact at a time, many at once: there is
+no batch of either (2026-10-25: "use the put and get"). A batch's
+bytes pass through the server's code, which on Workers costs CPU by the
+byte (a 40 MB one ran out of it), and its artifacts arrive one after
+another; a `GET`'s and a `PUT`'s bytes pass untouched, in parallel.
+
+## Limits
+
+An operator sets each; `GET /v1/capabilities` names them:
+
+```json
+{ "maxCheckHashes": 500, "maxUploadBytes": 100000000 }
+```
+
+A client keeps to the limits the server names.
+
+## Errors
+
+Every refusal is `{ code, message }`, `application/json`, its `message`
+saying what to fix:
+
+```json
+{ "code": "forbidden", "message": "this request reads only" }
+```
+
+A JSON body without `Content-Type: application/json` is `400`; an unknown
+route `404`; a route's wrong method `405` with `Allow`; a bucket that
+cannot be read or written `502` (an upload whose client left before
+its body ended is `400`, and logs nothing), and a failure the server
+did not expect `500`, each `message` what failed. Turbo's `teamId`
+and `slug` query parameters are `400`: the token names the repository.

package/README.md

@@ -1,3 +1,154 @@
 # @vzn/vx-cache-server
 
-Placeholder. Part of [vx](https://github.com/vznjs/vx).
+Website: <https://vznjs.github.io/vx/> · source: <https://github.com/vznjs/vx>
+
+A cache server for vx that you host yourself, for CI jobs. It stores
+task artifacts in one bucket and nothing else (no database), and speaks
+the [vx-cache protocol](./PROTOCOL.md) (`/v1`). Three ways to run it
+answer alike:
+
+- **Bun**, with any S3-compatible bucket; any number of nodes share one.
+- **Docker**, the same server as an image (`Dockerfile`).
+- **Cloudflare Workers**, with R2.
+
+`vxCache()`
+([`@vzn/vx-cache`](https://github.com/vznjs/vx/tree/main/packages/vx-cache))
+points `vx` at it.
+
+## CI tokens
+
+Every request names its issuer and repository by their hashes
+(`vx-issuer`, `vx-repository`; `vxCache({ issuer, repository })`). A
+CI job's carries its own OIDC token: there are no stored tokens
+(`vxCache()` asks GitHub for it; on GitLab name an `id_tokens` entry
+`VX_CACHE_TOKEN`). The token must be of the repository named, and it
+decides where the job writes: its own branch's scope, never another's.
+
+`ALLOW` says who may take part, the same string the DTE relay reads:
+entries separated by spaces, each `issuer:owner/repo:workflow`. For
+example:
+
+```sh
+ALLOW='https://token.actions.githubusercontent.com:acme/app:ci.yml https://gitlab.com:acme/web:.gitlab-ci.yml'
+```
+
+Only jobs of a workflow it names get in; any other job is refused. With
+`ALLOW` empty, the server does not start (a Worker refuses every request). A job writes its branch's own
+scope, which only runs of that branch read:
+
+- A push writes its branch, so a run of `main` writes `main`.
+- A pull request writes its merge ref, `refs/pull/<n>/merge`, never a
+  branch: its work never reaches `main`'s runs, nor a branch a fork names.
+- A merge queue's (`merge_group`) run (`refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>`)
+  writes its base branch, since queued code is about to land.
+- A `pull_request_target`, `issue_comment` or `workflow_run` run writes
+  nothing: it may run a fork's code.
+
+`AUDIENCE` is the `aud` a token must name: the origin clients reach the
+server at (`https://cache.example.com`), which is what `vxCache()` asks
+GitHub for. On Workers, unset, it is that origin: Cloudflare routes only
+the Worker's own hostnames to it. On Bun and Docker it is required, since
+there the origin is the request's `Host` header, which a client picks.
+`READ_ACCESS=public` lets a request with no token read a repository
+`ALLOW` names (a developer's laptop): it writes nothing. Unset, a
+request with no token is `401`.
+
+## On Bun
+
+```sh
+ALLOW='https://token.actions.githubusercontent.com:acme/app:ci.yml' \
+AUDIENCE=https://cache.example.com \
+S3_BUCKET=vx-cache S3_ENDPOINT=https://s3.example.com \
+S3_ACCESS_KEY_ID=… S3_SECRET_ACCESS_KEY=… \
+bun packages/vx-cache-server/src/bun.ts --port 8080
+```
+
+S3 settings are those Bun's S3 client reads (`S3_REGION` too). A node keeps no state of its own, so
+any number of them serve one bucket behind a balancer.
+
+## With Docker
+
+From the repo root:
+
+```sh
+docker build -f packages/vx-cache-server/Dockerfile -t vx-cache-server .
+docker run -p 8080:8080 -e ALLOW='…' -e AUDIENCE=https://cache.example.com -e S3_BUCKET=… -e S3_ENDPOINT=… \
+  -e S3_ACCESS_KEY_ID=… -e S3_SECRET_ACCESS_KEY=… vx-cache-server
+```
+
+With vx's other servers: [`compose.yaml`](https://github.com/vznjs/vx/blob/main/private/vx-servers/compose.yaml)
+builds and runs all three (`docker compose up -d`).
+
+## Limits
+
+`MAX_CHECK_HASHES` (lookups, hashes × scopes, a check makes; default
+500, 6 on Workers) and
+`MAX_UPLOAD_BYTES` (default 100 MB, one artifact) set
+the limits, each in decimal digits (on Workers, a JSON number too). Every `/v1/artifacts` answer, a refusal too, names them to
+clients (`vx-max-*`), and
+`GET /v1/capabilities` too.
+
+## On Cloudflare Workers
+
+From this directory, with `ALLOW` filled in `wrangler.jsonc`:
+
+```sh
+bun install
+bunx wrangler login
+bunx wrangler deploy
+```
+
+Wrangler makes the R2 bucket `wrangler.jsonc` names on the first deploy;
+the Worker reads it as the binding `BLOBS`.
+By default a check makes 6 lookups: a Worker request has 6 calls
+waiting at once and queues the rest, so checks of 6 sent at once are
+the fastest (from a GitHub runner, 134 hashes: 168 to 216 ms, against
+1.9 s for one check of 134, 2026-10-25). Each lookup is one subrequest
+(an R2 head), so a higher `MAX_CHECK_HASHES` must fit your plan's
+subrequests a request, and `MAX_UPLOAD_BYTES` your plan's request body.
+The server lowers neither. A download is read through the data center's cache: an
+artifact never changes, so after R2 serves it once, that data center
+answers it without R2 (free on every plan). Whether R2 holds an
+artifact (a check, a `HEAD`, an upload's skip) is asked of R2 alone: the
+data center's copy can outlive R2's, and a writer told "held" there
+would skip an upload another data center then cannot read. An upload
+drops the copy in the data center it reaches: R2 had let those bytes go.
+
+## Expiry
+
+The bucket's own lifecycle rule expires artifacts, by age since they
+were written; the server runs no sweep. An artifact's object name is
+`<issuer>/<repository>/<scope>/<hash>`, the first three each hashed (a
+client sends a scope as its ref's hash, never the ref), so one rule
+for the whole bucket is the one there is, for example 1 day:
+
+```sh
+bunx wrangler r2 bucket lifecycle add vx-cache all '' --expire-days 1
+```
+
+On S3 the same rule goes in the bucket's lifecycle configuration. A
+main run that misses an expired artifact runs the task and stores it
+again.
+
+## API
+
+The same server as a `fetch` handler, to mount in a server of your own,
+over a bucket of your own (`src/index.ts`):
+
+- `createCacheServer(options: ServerOptions)` returns
+  `(req: Request) => Promise<Response>`. `ServerOptions` is
+  `{ blobs, authorize, limits? }`: `blobs` is a `Blobs` bucket
+  (`{ put(name, body, size), get(name), size(name) }`, `get` answering a
+  `Blob`, `{ body, size }`), `authorize` an `Authorize`, which maps a
+  request to its `Access` (`{ issuer, repository, write? }`: the token's issuer and
+  repository name, which it reads, and the scope it may write) or throws, and `limits` any of `Limits`
+  (`{ maxCheckHashes, maxUploadBytes }`) over
+  `DEFAULT_LIMITS`.
+- `blobName(issuer, repository, scope, hash)` is an artifact's object name,
+  `<issuer>/<repository>/<scope>/<hash>`, issuer and repository each the first 128 bits
+  of their SHA-256 in hex and `scope` the ref's hash as a client sends
+  it (PROTOCOL.md § Keys), so no segment is a plain value.
+- `ALLOW` and the CI token check are [`@vzn/vx-devtools`](https://github.com/vznjs/vx/tree/main/packages/vx-devtools)'s,
+  the check every vx server shares.
+- `SCOPE_HEADER` (`vx-scope`) and `LIMIT_HEADERS` are the header names
+  (PROTOCOL.md).

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun 1.4.0's `--compile` binaries resolve an on-disk
+// package by `<pkg>/index.ts` and ignore package.json `exports` / `main`
+// (see packages/vx/index.ts). Same module as the exports map names.
+export * from './src/index.js'

package/package.json

@@ -1,8 +1,57 @@
 {
   "name": "@vzn/vx-cache-server",
-  "version": "0.0.0",
-  "description": "Placeholder; real releases are published by CI.",
+  "version": "0.0.649",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/vznjs/vx.git" },
-  "publishConfig": { "access": "public" }
+  "description": "A remote cache server for vx that you host: on Bun or Docker with an S3-compatible bucket, or on Cloudflare Workers with R2.",
+  "keywords": [
+    "vx",
+    "monorepo",
+    "remote-cache",
+    "cache-server"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "vx-cache-server": "./src/bun.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "import": "./src/worker.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "Dockerfile",
+    "PROTOCOL.md",
+    "wrangler.jsonc",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "//": [
+    "wrangler: deploys src/worker.ts by wrangler.jsonc.",
+    "@vzn/vx: vx.config.ts's core; `*`, not workspace:, which npm refuses when a deploy installs this directory alone.",
+    "@vzn/vx-devtools: checks the CI tokens, the check vx's servers share (it imports only jose); `*` for the same reason.",
+    "jose: the tests sign the CI tokens the server checks.",
+    "miniflare: tests/worker.test.ts runs src/worker.ts in workerd with R2, as Workers deploy it."
+  ],
+  "dependencies": {
+    "@vzn/vx-devtools": "0.0.649"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-cache-server"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-cache-server#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
 }

package/src/bun.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env -S bun --no-env-file --no-install
+// `vx-cache-server` on Bun: artifacts in an S3-compatible bucket, nothing
+// else, so any number of nodes share one bucket (PROTOCOL.md, README.md).
+
+import { parseArgs } from 'node:util'
+import { oidcAuth, parseAllow, Refusal, statusLine } from '@vzn/vx-devtools'
+import { isCount } from './protocol.js'
+import { createCacheServer, DEFAULT_LIMITS, limitsFrom } from './server.js'
+import type { Blobs } from './store.js'
+
+const USAGE = `usage: vx-cache-server [--port 8080] [--host 0.0.0.0]
+  ALLOW           who may take part, space separated, each issuer:owner/repo:workflow
+                  (README.md § CI tokens); only their jobs' OIDC tokens are taken
+  AUDIENCE        the aud a CI token names: the URL clients reach this server at
+  READ_ACCESS     public: a request with no token reads a repository ALLOW names
+  S3_BUCKET       the bucket; S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID and
+                  S3_SECRET_ACCESS_KEY as Bun's S3 client reads them
+  MAX_CHECK_HASHES  lookups one check makes, hashes × scopes (default ${DEFAULT_LIMITS.maxCheckHashes})
+  MAX_UPLOAD_BYTES  the largest upload, one artifact (default ${DEFAULT_LIMITS.maxUploadBytes})`
+
+/**
+ * An S3-compatible bucket through Bun's S3 client. Reads go through a
+ * presigned URL: one request answers a GET's bytes and size, or its 404,
+ * and Bun answers `new Response(s3File)` with a redirect a client may not
+ * reach.
+ */
+export function s3Blobs(client: Bun.S3Client): Blobs {
+  const ask = async (name: string, method: 'GET' | 'HEAD'): Promise<Response | null> => {
+    // Identity: Bun's fetch asks for gzip and inflates it, and a
+    // compressed answer's Content-Length is not the artifact's size.
+    const res = await fetch(client.presign(name, { method }), {
+      method,
+      headers: { 'accept-encoding': 'identity' },
+    })
+    if (res.status === 404) {
+      await res.body?.cancel()
+      return null
+    }
+    if (!res.ok) {
+      await res.body?.cancel()
+      throw new Error(`the bucket answered ${method} ${res.status}`)
+    }
+    return res
+  }
+  return {
+    async put(name, body, size) {
+      let seen = 0
+      const counted = body.pipeThrough(
+        new TransformStream<Uint8Array, Uint8Array>({
+          transform(chunk, controller) {
+            seen += chunk.byteLength
+            if (seen > size) throw new Refusal(400, `the body is longer than ${size} bytes`)
+            controller.enqueue(chunk)
+          },
+          flush() {
+            if (seen !== size) throw new Refusal(400, `the body is ${seen} bytes, not ${size}`)
+          },
+        }),
+      )
+      await client.write(name, new Response(counted))
+    },
+    async get(name) {
+      const res = await ask(name, 'GET')
+      if (res === null) return null
+      return {
+        body: res.body ?? new Blob([]).stream(),
+        size: Number(res.headers.get('content-length')),
+      }
+    },
+    async size(name) {
+      const res = await ask(name, 'HEAD')
+      if (res === null) return null
+      // Number(null) is 0: a HEAD naming no length is no size, not an empty artifact.
+      const length = res.headers.get('content-length')
+      const size = length === null || length.trim() === '' ? Number.NaN : Number(length)
+      if (!isCount(size)) throw new Error('the bucket answered HEAD with no Content-Length')
+      return size
+    },
+  }
+}
+
+/**
+ * The handler on Bun.serve. Bun's own body limit is lifted: the handler
+ * refuses an upload past `MAX_UPLOAD_BYTES` by its Content-Length, as a
+ * `{ code, message }`, where Bun's 413 had no body and the client warned
+ * with no reason.
+ */
+export function listen(
+  fetch: (req: Request) => Promise<Response>,
+  hostname: string,
+  port: number,
+): Bun.Server<undefined> {
+  return Bun.serve({ hostname, port, maxRequestBodySize: Number.MAX_SAFE_INTEGER, fetch })
+}
+
+function main(argv: string[]): void {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      port: { type: 'string', default: '8080' },
+      host: { type: 'string', default: '0.0.0.0' },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  })
+  if (values.help) {
+    console.log(USAGE)
+    return
+  }
+  const env = Bun.env
+  if (env.S3_BUCKET === undefined || env.S3_BUCKET === '') fail(`set S3_BUCKET\n${USAGE}`)
+  // Digits only: Number('') is 0, a random port for `--port "$PORT"` with
+  // PORT unset, and Number read 0x50 as 80 and 1e1 as 10.
+  const port = /^\d+$/.test(values.port) ? Number(values.port) : Number.NaN
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    fail(`--port: not a port: ${values.port}`)
+  // Bun.serve reads '' as localhost: unreachable from another host or container.
+  if (values.host.trim() === '') fail(`--host: needs an address, got '${values.host}'`)
+  let allow
+  let limits
+  try {
+    allow = parseAllow(env.ALLOW ?? '')
+  } catch (err) {
+    fail(`ALLOW: ${(err as Error).message}`)
+  }
+  // An empty one started a server that refused every request.
+  if (allow.length === 0) fail(`set ALLOW\n${USAGE}`)
+  try {
+    limits = { ...DEFAULT_LIMITS, ...limitsFrom(env) }
+  } catch (err) {
+    fail((err as Error).message)
+  }
+  const client = new Bun.S3Client({ bucket: env.S3_BUCKET })
+  try {
+    // Signs offline: refuses missing credentials now, not every request 502.
+    client.presign('vx-cache-server')
+  } catch (err) {
+    fail(`S3: ${(err as Error).message}`)
+  }
+  // Unset, the audience would be the origin a request names: its Host
+  // header, which the client picks. Workers know their own hostnames.
+  const audience = env.AUDIENCE?.trim() ?? ''
+  if (audience === '')
+    fail(`set AUDIENCE: the aud a CI token names, the URL clients reach this server at\n${USAGE}`)
+  const handle = createCacheServer({
+    blobs: s3Blobs(client),
+    authorize: oidcAuth({
+      allow,
+      readAccess: env.READ_ACCESS,
+      audience,
+    }),
+    limits,
+  })
+  const server = listen(handle, values.host, port)
+  process.stdout.write(statusLine('ok', 'vx-cache-server', `listening on ${server.url.href}`))
+  const stop = (): void => void server.stop().then(() => process.exit(0))
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+}
+
+function fail(message: string): never {
+  process.stderr.write(statusLine('err', 'vx-cache-server', message))
+  process.exit(2)
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (err) {
+    // parseArgs names the flag it refused, not the ones there are.
+    const usage = (err as { code?: string }).code?.startsWith('ERR_PARSE_ARGS') ? `\n${USAGE}` : ''
+    fail(`${err instanceof Error ? err.message : String(err)}${usage}`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// @vzn/vx-cache-server: a remote cache server for vx, on Bun with an
+// S3-compatible bucket or on Cloudflare Workers with R2.
+
+export { LIMIT_HEADERS, SCOPE_HEADER } from './protocol.js'
+export { createCacheServer, DEFAULT_LIMITS, type Limits, type ServerOptions } from './server.js'
+export { type Blob, blobName, type Blobs } from './store.js'

package/src/protocol.ts

@@ -0,0 +1,23 @@
+// The wire of vx-cache v1 (PROTOCOL.md): names, limits and the parsers of
+// what a request carries. Every string a client sends is opaque to the
+// server, which only compares it, so a client can send it encrypted.
+
+/** The scope (a ref's hash) a download reads: `GET /v1/artifacts/<hash>`. */
+export const SCOPE_HEADER = 'vx-scope'
+
+/**
+ * The limits a server sets, as headers on every `/v1/artifacts`
+ * answer: a client batches checks only by what it was told.
+ */
+export const LIMIT_HEADERS = {
+  maxCheckHashes: 'vx-max-check-hashes',
+  maxUploadBytes: 'vx-max-upload-bytes',
+} as const
+
+/** An artifact's hash, as Turbo's spec has it (hex), and at most 128 long. */
+const HASH = /^[a-fA-F0-9]{1,128}$/
+
+export const isHash = (s: string): boolean => HASH.test(s)
+
+export const isCount = (n: unknown): n is number =>
+  typeof n === 'number' && Number.isSafeInteger(n) && n >= 0

package/src/server.ts

@@ -0,0 +1,294 @@
+// vx-cache v1 (PROTOCOL.md) over any `Blobs` bucket: one fetch handler
+// the Bun server, the Worker and the Docker image all serve. No database:
+// an artifact is one object, named by its issuer, repository name, scope and
+// hash, and a read names the exact scope it wants (2026-10-25).
+
+import {
+  type Access,
+  type Authorize,
+  errorJson,
+  hashPart,
+  notAllowed,
+  Refusal,
+} from '@vzn/vx-devtools'
+import { isCount, isHash, LIMIT_HEADERS, SCOPE_HEADER } from './protocol.js'
+import { blobName, type Blobs } from './store.js'
+
+/** What an operator may set; each defaults, and a backend may cap them. */
+export interface Limits {
+  /** The lookups one check makes: its hashes times its scopes. */
+  readonly maxCheckHashes: number
+  /** The largest upload, in bytes: one artifact. */
+  readonly maxUploadBytes: number
+}
+
+export const DEFAULT_LIMITS: Limits = {
+  maxCheckHashes: 500,
+  maxUploadBytes: 100_000_000,
+}
+
+export interface ServerOptions {
+  blobs: Blobs
+  authorize: Authorize
+  limits?: Partial<Limits>
+}
+
+const VARS = {
+  maxCheckHashes: 'MAX_CHECK_HASHES',
+  maxUploadBytes: 'MAX_UPLOAD_BYTES',
+} as const
+
+/**
+ * `MAX_CHECK_HASHES` and `MAX_UPLOAD_BYTES` from the environment, each a
+ * whole number above 0: a string, or a number as wrangler.jsonc may write
+ * it (a number was skipped, unsaid, for the default).
+ */
+export function limitsFrom(env: object): Partial<Limits> {
+  const out: Partial<Record<keyof Limits, number>> = {}
+  for (const [field, name] of Object.entries(VARS) as [keyof Limits, string][]) {
+    const v = (env as Record<string, unknown>)[name]
+    if (v === undefined || v === '') continue
+    // A Worker var may be JSON: a number was skipped, the default served.
+    // A string is digits only, as --port is: Number read 0x10 as 16.
+    const n =
+      typeof v === 'number' ? v : typeof v === 'string' && /^\d+$/.test(v) ? Number(v) : Number.NaN
+    if (!(Number.isSafeInteger(n) && n > 0))
+      throw new Error(
+        `${name}: not a whole number above 0: ${typeof v === 'string' || typeof v === 'number' ? v : JSON.stringify(v)}`,
+      )
+    out[field] = n
+  }
+  return out
+}
+
+/** A held artifact's bytes never change (2026-10-25). */
+const IMMUTABLE = 'private, max-age=31536000, immutable'
+
+/** A scope on the wire: its ref's `hashPart`, so no ref is ever sent or stored plain (2026-10-25). */
+const SCOPE = /^[0-9a-f]{32}$/
+
+export function createCacheServer(opts: ServerOptions): (req: Request) => Promise<Response> {
+  const { blobs, authorize } = opts
+  const limits: Limits = { ...DEFAULT_LIMITS, ...opts.limits }
+  const limitHeaders = Object.fromEntries(
+    Object.entries(LIMIT_HEADERS).map(([k, h]) => [h, String(limits[k as keyof Limits])]),
+  )
+
+  /** The scope a client names: a ref's hash, read as it is. */
+  const scopeOf = (scope: unknown): string => {
+    if (typeof scope !== 'string' || !SCOPE.test(scope)) {
+      throw new Refusal(400, "scope: a ref's hash, 32 hex digits (PROTOCOL.md § Keys)")
+    }
+    return scope
+  }
+  const nameOf = (access: Access, scope: string, hash: string): Promise<string> =>
+    blobName(access.issuer, access.repository, scope, hash)
+  /** A read of the bucket: one it fails is its fault, `502`, never the server's `500`. */
+  const read = async <T>(ask: Promise<T>): Promise<T> => {
+    try {
+      return await ask
+    } catch (err) {
+      throw new Refusal(502, `the bucket could not be read: ${message(err)}`)
+    }
+  }
+
+  /** The token's own scope, the one place it writes. */
+  const writeScope = (access: Access): Promise<string> => {
+    if (access.write === undefined) throw new Refusal(403, 'this request reads only')
+    return hashPart(access.write)
+  }
+
+  /**
+   * `{ hashes, scopes }`: Turbo's batch query, with the scopes to read in
+   * the order to read them; up to `max` lookups, hashes times scopes.
+   */
+  async function queryOf(req: Request, max: number) {
+    const body = await readJson(req, max * 140 + 100)
+    const hashes = field(body, 'hashes')
+    const scopes = field(body, 'scopes')
+    if (!Array.isArray(hashes) || !hashes.every((h) => typeof h === 'string' && isHash(h))) {
+      throw new Refusal(400, 'hashes: a list of 1 to 128 hex digits each')
+    }
+    if (!Array.isArray(scopes) || scopes.length === 0) {
+      throw new Refusal(400, "scopes: a list of refs' hashes, in the order to read them")
+    }
+    if (hashes.length * scopes.length > max) {
+      throw new Refusal(400, `hashes × scopes: up to ${max} lookups`)
+    }
+    return { hashes: hashes as string[], scopes: scopes.map(scopeOf) }
+  }
+
+  async function artifact(req: Request, hash: string): Promise<Response> {
+    if (!isHash(hash)) throw new Refusal(400, 'a hash is 1 to 128 hex digits')
+    const access = await authorize(req)
+    const scope = scopeOf(req.headers.get(SCOPE_HEADER))
+    const blob = await read(blobs.get(await nameOf(access, scope, hash)))
+    if (blob === null) return errorJson(404, 'no artifact under this key')
+    return new Response(blob.body, {
+      headers: {
+        'content-length': String(blob.size),
+        'content-type': 'application/octet-stream',
+        // An artifact never changes under its key; private: its token chose the repository.
+        'cache-control': IMMUTABLE,
+      },
+    })
+  }
+
+  /** Turbo's `HEAD /v8/artifacts/<hash>`: whether the scope named holds it, and its size, with no bytes. */
+  async function exists(req: Request, hash: string): Promise<Response> {
+    if (!isHash(hash)) throw new Refusal(400, 'a hash is 1 to 128 hex digits')
+    const access = await authorize(req)
+    const scope = scopeOf(req.headers.get(SCOPE_HEADER))
+    const size = await read(blobs.size(await nameOf(access, scope, hash)))
+    if (size === null) return new Response(null, { status: 404 })
+    return new Response(null, {
+      headers: { 'content-length': String(size), 'cache-control': IMMUTABLE },
+    })
+  }
+
+  // Every lookup at once, each exact: a hash answers the first scope
+  // asked that holds it, and names it, for the download to read.
+  async function check(req: Request): Promise<Response> {
+    const access = await authorize(req)
+    const { hashes, scopes } = await queryOf(req, limits.maxCheckHashes)
+    const sizes = await Promise.all(
+      hashes.map((hash) =>
+        Promise.all(scopes.map(async (s) => read(blobs.size(await nameOf(access, s, hash))))),
+      ),
+    )
+    const held = Object.fromEntries(
+      hashes.map((hash, i) => {
+        const at = sizes[i]!.findIndex((size) => size !== null)
+        return [hash, at < 0 ? null : { size: sizes[i]![at], scope: scopes[at] }]
+      }),
+    )
+    return Response.json(held)
+  }
+
+  /**
+   * An upload: one artifact, its bytes the whole body (Turbo's
+   * `PUT /v8/artifacts/<hash>`), stored in the token's scope. They reach
+   * the bucket without passing through this code, so a large one costs
+   * no CPU here (2026-10-25: no batch upload; a batch is split by this
+   * code, and on Workers a 40 MB one ran out of CPU).
+   */
+  async function put(req: Request, hash: string): Promise<Response> {
+    if (!isHash(hash)) throw new Refusal(400, 'a hash is 1 to 128 hex digits')
+    const access = await authorize(req)
+    const name = await nameOf(access, await writeScope(access), hash)
+    const length = contentLength(req)
+    if (length > limits.maxUploadBytes) {
+      throw new Refusal(413, `an upload is at most ${limits.maxUploadBytes} bytes`)
+    }
+    if ((await read(blobs.size(name))) !== null) {
+      await req.body?.cancel()
+      return new Response(null, { status: 204 })
+    }
+    try {
+      await blobs.put(name, req.body ?? new Blob([]).stream(), length)
+    } catch (err) {
+      if (err instanceof Refusal) throw err
+      // A client that left mid-body (a cancelled run, a dropped link) fails
+      // the bucket's write too: no fault of the bucket's, nor the operator's.
+      if (req.signal.aborted) {
+        throw new Refusal(400, 'the upload ended before its body did: the client left')
+      }
+      throw new Refusal(502, `the bucket refused the artifact: ${message(err)}`)
+    }
+    return new Response(null, { status: 204 })
+  }
+
+  return async (req) => {
+    const res = await answer(req)
+    // Every /v1/artifacts answer, a refusal too: a client holding older
+    // limits (a restart with new ones, a Worker's rollout) learns them from
+    // the answer that refused it, or it was refused every check of the run.
+    if (/^\/v1\/artifacts(\/|$)/.test(new URL(req.url).pathname))
+      for (const [h, v] of Object.entries(limitHeaders)) res.headers.set(h, v)
+    return res
+  }
+
+  async function answer(req: Request): Promise<Response> {
+    const url = new URL(req.url)
+    try {
+      const path = url.pathname
+      // Turbo's team params are not taken: a repository is its token's.
+      if (url.searchParams.has('teamId') || url.searchParams.has('slug')) {
+        throw new Refusal(400, 'teamId and slug are not taken: the token names the repository')
+      }
+      if (path === '/v1/capabilities') {
+        if (req.method !== 'GET') return notAllowed('GET')
+        await authorize(req)
+        return Response.json(limits)
+      }
+      if (path === '/v1/artifacts') {
+        return req.method === 'POST' ? await check(req) : notAllowed('POST')
+      }
+      if (path.startsWith('/v1/artifacts/') && !path.slice('/v1/artifacts/'.length).includes('/')) {
+        const hash = path.slice('/v1/artifacts/'.length)
+        if (req.method === 'GET') return await artifact(req, hash)
+        if (req.method === 'HEAD') return await exists(req, hash)
+        return req.method === 'PUT' ? await put(req, hash) : notAllowed('GET, HEAD, PUT')
+      }
+      return errorJson(
+        404,
+        `no route ${req.method} ${path.slice(0, 200)}: name the server's base URL; it serves /v1/ (PROTOCOL.md)`,
+      )
+    } catch (err) {
+      if (err instanceof Refusal) {
+        // The bucket's or the issuer's fault is the operator's to see too.
+        if (err.status >= 500)
+          console.error(`vx-cache-server: ${req.method} ${url.pathname}: ${err.message}`)
+        return errorJson(err.status, err.message)
+      }
+      // Never swallowed: the client warns with what the server says.
+      console.error(`vx-cache-server: ${req.method} ${url.pathname}: ${String(err)}`)
+      return errorJson(500, message(err))
+    }
+  }
+}
+
+const message = (err: unknown): string => (err instanceof Error ? err.message : String(err))
+
+async function readJson(req: Request, max: number): Promise<unknown> {
+  if (!/^application\/json\b/i.test(req.headers.get('content-type') ?? '')) {
+    throw new Refusal(400, 'send the body as Content-Type: application/json')
+  }
+  if (Number(req.headers.get('content-length') ?? 0) > max) {
+    throw new Refusal(413, `the body is at most ${max} bytes`)
+  }
+  const text = await textUpTo(req, max)
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Refusal(400, 'the body is not JSON')
+  }
+}
+
+function contentLength(req: Request): number {
+  const length = req.headers.get('content-length')
+  if (length === null) throw new Refusal(400, 'an upload names its Content-Length')
+  const size = Number(length)
+  if (!isCount(size)) throw new Refusal(400, 'Content-Length is not a byte count')
+  return size
+}
+
+const field = (body: unknown, name: string): unknown =>
+  typeof body === 'object' && body !== null ? (body as Record<string, unknown>)[name] : undefined
+
+/**
+ * The body as text, refused past `max` bytes as they arrive: a chunked body
+ * names no length, and was read whole before it was measured.
+ */
+async function textUpTo(req: Request, max: number): Promise<string> {
+  const decoder = new TextDecoder()
+  let text = ''
+  let seen = 0
+  // Leaving the loop by a throw cancels the stream.
+  for await (const chunk of req.body ?? []) {
+    seen += chunk.byteLength
+    if (seen > max) throw new Refusal(413, `the body is at most ${max} bytes`)
+    text += decoder.decode(chunk, { stream: true })
+  }
+  return text + decoder.decode()
+}

package/src/store.ts

@@ -0,0 +1,35 @@
+// Where a server keeps what it is sent: one bucket (S3 or R2), no
+// database (2026-10-25). An artifact is one object whose name is its
+// issuer, repository name, scope and hash and whose size is the bucket's
+// own, so any number of nodes share a bucket and nothing else.
+
+import { hashPart } from '@vzn/vx-devtools'
+
+/** A blob's bytes and its size, as the bucket holds them. */
+export interface Blob {
+  readonly body: ReadableStream<Uint8Array>
+  readonly size: number
+}
+
+/** A bucket of blobs by name; a put replaces a name whole. */
+export interface Blobs {
+  /** Stores `size` bytes; rejects when the stream ends at another length. */
+  put(name: string, body: ReadableStream<Uint8Array>, size: number): Promise<void>
+  /** The blob, or null when the bucket has none by that name. */
+  get(name: string): Promise<Blob | null>
+  /** Its size, read off its metadata, or null when there is none. */
+  size(name: string): Promise<number | null>
+}
+
+/**
+ * An artifact's object name, `<issuer>/<id>/<scope>/<hash>`
+ * (2026-10-25): issuer and id each hashed (`hashPart`), `scope` the ref's
+ * hash the client sent, so no segment is a plain value and a ref's slashes
+ * or any byte stay one segment. The server knows no tier.
+ */
+export const blobName = async (
+  issuer: string,
+  id: string,
+  scope: string,
+  hash: string,
+): Promise<string> => `${await hashPart(issuer)}/${await hashPart(id)}/${scope}/${hash}`

package/src/worker.ts

@@ -0,0 +1,181 @@
+// `vx-cache-server` on Cloudflare Workers: artifacts in R2, nothing else.
+// `wrangler.jsonc` deploys it; ALLOW, AUDIENCE and the limits are vars in
+// it (README.md § On Cloudflare Workers).
+
+import { type Authorize, errorJson, oidcAuth, parseAllow, Refusal } from '@vzn/vx-devtools'
+import { createCacheServer, DEFAULT_LIMITS, type Limits, limitsFrom } from './server.js'
+import type { Blobs } from './store.js'
+
+/** The parts of the Workers runtime this file uses, so it needs no types package. */
+export interface R2Bucket {
+  put(name: string, body: ReadableStream<Uint8Array>): Promise<unknown>
+  get(name: string): Promise<{ body: ReadableStream<Uint8Array>; size: number } | null>
+  head(name: string): Promise<{ size: number } | null>
+}
+/** The data center's cache (Workers Cache API): free, and per data center. */
+interface WorkersCache {
+  match(key: Request): Promise<Response | undefined>
+  put(key: Request, res: Response): Promise<void>
+  delete(key: Request): Promise<boolean>
+}
+declare const caches: { open(name: string): Promise<WorkersCache> }
+export interface Context {
+  waitUntil(p: Promise<unknown>): void
+}
+declare const FixedLengthStream: new (length: number) => {
+  readable: ReadableStream<Uint8Array>
+  writable: WritableStream<Uint8Array>
+}
+
+export interface Env {
+  readonly BLOBS?: R2Bucket
+  /** Who may take part (`parseAllow`): `issuer:owner/repo:workflow` entries, space separated. */
+  readonly ALLOW?: string
+  /** The `aud` a CI token names; unset, the origin the Worker is reached at. */
+  readonly AUDIENCE?: string
+  /** `public`: a request with no token reads a repository ALLOW names. */
+  readonly READ_ACCESS?: string
+  /** A string, or a number as wrangler.jsonc may write it. */
+  readonly MAX_CHECK_HASHES?: string | number
+  readonly MAX_UPLOAD_BYTES?: string | number
+}
+
+/** An object's key in the data center's cache. */
+const keyOf = (name: string): Request => new Request(`https://vx-cache.blobs/${name}`)
+
+/**
+ * R2, read through the data center's cache: an artifact never changes
+ * under its name while R2 holds it, so a copy needs no expiry of its own;
+ * an upload drops the copy, of bytes R2 has since let go. The server has
+ * checked the token and named the object before a read reaches here.
+ */
+
+export function r2Blobs(bucket: R2Bucket, cache: Promise<WorkersCache>, ctx: Context): Blobs {
+  return {
+    async put(name, body, size) {
+      // R2 takes a stream of known length; this one errors at any other.
+      const fixed = new FixedLengthStream(size)
+      const piped = body.pipeTo(fixed.writable)
+      const [stored, read] = await Promise.allSettled([bucket.put(name, fixed.readable), piped])
+      // A body of another length fails the pipe and R2's read of it with
+      // one error. R2 failing of its own is the bucket's fault (a 502),
+      // never the client's 400, though its stream's cancel fails the pipe.
+      if (
+        stored.status === 'rejected' &&
+        (read.status === 'fulfilled' || stored.reason !== read.reason)
+      )
+        throw stored.reason
+      if (read.status === 'rejected')
+        throw new Refusal(400, `the body is not ${size} bytes: ${String(read.reason)}`)
+      // R2 takes a name only once it holds none: a copy here is of bytes
+      // R2 expired, a corrupt one too, and outlived the new ones a year.
+      await (await cache).delete(keyOf(name))
+    },
+    get: async (name) => {
+      const key = keyOf(name)
+      const hit = await (await cache).match(key)
+      if (hit?.body) return { body: hit.body, size: Number(hit.headers.get('content-length')) }
+      const o = await bucket.get(name)
+      if (o === null) return null
+      // The copy is R2 read again, never a tee of the client's body: a tee
+      // on Workers reads at its slower branch's pace, and the cache write
+      // held a download for 19 minutes (main, 2026-10-28).
+      ctx.waitUntil(
+        (async () => {
+          const again = await bucket.get(name)
+          if (again === null) return
+          const headers = {
+            'content-length': String(again.size),
+            'cache-control': 'public, max-age=31536000, immutable',
+          }
+          await (await cache).put(key, new Response(again.body, { headers }))
+        })(),
+      )
+      return { body: o.body, size: o.size }
+    },
+    // R2 alone answers whether it holds an object: a check, a HEAD and a
+    // PUT's skip. The data center's copy outlives R2's (expiry, a wipe), so
+    // a writer told "held" there skipped its upload and a reader in another
+    // data center found nothing (2026-10-27: a DTE worker's save, then the
+    // run's read, a 404).
+    size: async (name) => (await bucket.head(name))?.size ?? null,
+  }
+}
+
+/**
+ * A check's lookups by default: a Worker request has 6 calls waiting on R2
+ * at once and queues the rest, so a check of 6 answers in one round and a
+ * client sends many at once (measured, 2026-10-25: 6 heads 64 ms, 24 341
+ * ms, 134 1.1-1.4 s; from a GitHub runner, 134 hashes, half held: 23
+ * checks of 6 at once 168-216 ms median, 134 single lookups 246-349 ms,
+ * one check of 134 1.9 s). A list is no way round it: a scope may hold
+ * billions.
+ */
+const CHECK_LOOKUPS = 6
+
+/**
+ * The limits as set, unclamped: a plan's limits are the operator's to set
+ * (2026-10-25: never optimize for the free plan).
+ */
+function workerLimits(env: Env): Limits {
+  return { ...DEFAULT_LIMITS, maxCheckHashes: CHECK_LOOKUPS, ...limitsFrom(env) }
+}
+
+/** What a request shares per isolate and settings. */
+let made: { key: string; authorize: Authorize; limits: Limits } | undefined
+
+export default {
+  async fetch(req: Request, env: Env, ctx: Context): Promise<Response> {
+    // A deploy's mistake, not R2's outage: unbound, every read was a 502.
+    if (env.BLOBS === undefined) {
+      return errorJson(500, 'BLOBS: bind an R2 bucket as BLOBS (wrangler.jsonc r2_buckets)')
+    }
+    const key = [
+      env.ALLOW,
+      env.AUDIENCE,
+      env.READ_ACCESS,
+      env.MAX_CHECK_HASHES,
+      env.MAX_UPLOAD_BYTES,
+    ].join('\0')
+    if (made?.key !== key) {
+      let allow
+      let limits
+      // wrangler.jsonc may write a var as JSON: a list reached parseAllow.
+      if (env.ALLOW !== undefined && typeof env.ALLOW !== 'string') {
+        return errorJson(
+          500,
+          'ALLOW: one string of issuer:owner/repo:workflow entries, space separated',
+        )
+      }
+      // Likewise AUDIENCE: "env.AUDIENCE.trim is not a function".
+      if (env.AUDIENCE !== undefined && typeof (env.AUDIENCE as unknown) !== 'string') {
+        return errorJson(500, 'AUDIENCE: one string, the aud CI tokens name')
+      }
+      try {
+        allow = parseAllow(env.ALLOW ?? '')
+      } catch (err) {
+        return errorJson(500, `ALLOW: ${(err as Error).message}`)
+      }
+      let authorize
+      try {
+        limits = workerLimits(env)
+        authorize = oidcAuth({
+          allow,
+          readAccess: env.READ_ACCESS,
+          // jose matches aud exactly: a pasted newline refused every
+          // token as the wrong audience.
+          ...(env.AUDIENCE ? { audience: env.AUDIENCE.trim() } : {}),
+        })
+      } catch (err) {
+        return errorJson(500, (err as Error).message)
+      }
+      made = { key, authorize, limits }
+    }
+    // The bucket and cache are this request's: a Worker's I/O objects do not outlive it.
+    return createCacheServer({
+      blobs: r2Blobs(env.BLOBS, caches.open('vx-cache'), ctx),
+      authorize: made.authorize,
+      limits: made.limits,
+    })(req)
+  },
+}

package/wrangler.jsonc

@@ -0,0 +1,16 @@
+// vx-cache-server on Cloudflare Workers (src/worker.ts): `bunx wrangler
+// deploy` from this directory. Artifacts live in R2, and nothing else.
+{
+  "name": "vx-cache-server",
+  "main": "src/worker.ts",
+  "compatibility_date": "2026-10-01",
+  "workers_dev": true,
+  // ALLOW: who may take part, issuer:owner/repo:workflow entries
+  // separated by spaces (README.md § CI tokens); empty, every request is
+  // refused with "set ALLOW". AUDIENCE: the aud a
+  // CI token names, unset the Worker's own origin. MAX_CHECK_HASHES
+  // and MAX_UPLOAD_BYTES set the limits, a string or a number (PROTOCOL.md).
+  "vars": { "ALLOW": "" },
+  // Expiry is the bucket's lifecycle rules (README.md § Expiry).
+  "r2_buckets": [{ "binding": "BLOBS", "bucket_name": "vx-cache" }],
+}