diff --git a/.github/workflows/pr-merge-review.yml b/.github/workflows/pr-merge-review.yml index 5d1be173821..193119c4581 100644 --- a/.github/workflows/pr-merge-review.yml +++ b/.github/workflows/pr-merge-review.yml @@ -7,6 +7,7 @@ on: - Runner Windows - Sentry SDK contract - Docker Runner check + - Runner image - commitperclip PR Review - Storybook Visual - Storybook Deploy diff --git a/.github/workflows/runner-image.yml b/.github/workflows/runner-image.yml new file mode 100644 index 00000000000..ccbf4c69460 --- /dev/null +++ b/.github/workflows/runner-image.yml @@ -0,0 +1,228 @@ +name: Runner image + +# Builds and checks the Runner image: the `runner-artifacts` target of the +# Dockerfile, a plain file tree that other image builds copy the Runner from. +# doc/runner-image-contract.md is the contract. +# +# This workflow builds and checks only. It has no access to a registry and +# publishes nothing. +on: + pull_request: + # Every input of scripts/runner-image-identity.mjs, .dockerignore (it + # decides which of those files the build receives), and the pipeline's + # own files. A test checks that every identity input is covered. + paths: + - .github/workflows/runner-image.yml + - Dockerfile + - .dockerignore + - .npmrc + - package.json + - pnpm-lock.yaml + - pnpm-workspace.yaml + - tsconfig.base.json + - patches/** + - packages/paperclip-runner/** + - packages/paperclip-eval-kernel/** + - packages/shared/src/provider-failure.generated.ts + - scripts/create-provider-pack-archive.mjs + - scripts/link-plugin-dev-sdk.mjs + - scripts/runner-image-identity.mjs + - scripts/runner-image-layout.mjs + - docker/runner-image/** + workflow_dispatch: + +# Least privilege: nothing at the workflow level, and read-only contents in +# each job. +permissions: {} + +# A newer push to a pull request replaces its older run. +concurrency: + group: runner-image-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + identity: + name: Resolve the Runner image identity + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: read + outputs: + digest: ${{ steps.identity.outputs.digest }} + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false + + - name: Setup pnpm + uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6 + with: + version: 9.15.4 + run_install: false + + # No dependency cache: a restored cache must not reach the image. + - name: Setup Node.js + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 + with: + node-version: 24 + package-manager-cache: false + + # A contributor cannot edit pnpm-lock.yaml, so a pull request that + # changes the Runner's dependencies is built against a lockfile resolved + # here. The image build installs from it frozen. + - name: Resolve the lockfile + run: | + set -euo pipefail + pnpm install --resolution-only --ignore-scripts --no-frozen-lockfile + + changed="$(git status --porcelain)" + if [ -n "$changed" ] && printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then + echo "Unexpected files changed during lockfile resolution:" + echo "$changed" + exit 1 + fi + echo "This run built from a \`pnpm-lock.yaml\` resolved for it${changed:+ (it differs from the committed file)}." >> "$GITHUB_STEP_SUMMARY" + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4 + with: + buildkitd-config-inline: | + [registry."docker.io"] + mirrors = ["mirror.gcr.io"] + + # Computed inside the build, from the files the build context supplies + # after .dockerignore. A digest computed from the checkout would cover + # files the image build never receives. + - name: Compute the identity in the build context + id: identity + run: | + set -euo pipefail + out="$RUNNER_TEMP/runner-image-identity" + docker buildx build --target runner-artifacts-identity --output "type=local,dest=$out" . + digest="$(jq -er .digest "$out/runner-image-identity.json")" + [[ "$digest" =~ ^[0-9a-f]{64}$ ]] + echo "digest=$digest" >> "$GITHUB_OUTPUT" + { + echo "Runner image inputs digest: \`$digest\`" + echo + echo '```json' + cat "$out/runner-image-identity.json" + echo '```' + } >> "$GITHUB_STEP_SUMMARY" + + # The legs must build from the file the identity was computed from, not + # from a second resolution. + - name: Keep the resolved lockfile for the build legs + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 + with: + name: runner-image-lockfile + path: pnpm-lock.yaml + if-no-files-found: error + retention-days: 1 + + # Multi-arch by native runner, not QEMU, as in docker.yml. GitHub-hosted + # runners: the protected release fleets admit only docker.yml on master. + # + # These legs hold no credential and use no registry build cache. The install + # runs dependency lifecycle scripts. + build: + name: Build and check (${{ matrix.arch }}) + needs: identity + strategy: + fail-fast: false + matrix: + include: + - platform: linux/amd64 + runner: ubuntu-latest + arch: amd64 + - platform: linux/arm64 + runner: ubuntu-24.04-arm + arch: arm64 + runs-on: ${{ matrix.runner }} + timeout-minutes: 60 + permissions: + contents: read + env: + DIGEST: ${{ needs.identity.outputs.digest }} + ARCH: ${{ matrix.arch }} + PLATFORM: ${{ matrix.platform }} + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + persist-credentials: false + + - name: Setup Node.js + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 + with: + node-version: 24 + package-manager-cache: false + + - name: Download the resolved lockfile + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 + with: + name: runner-image-lockfile + path: ${{ runner.temp }}/runner-image-lockfile + + - name: Use the resolved lockfile + run: cp "$RUNNER_TEMP/runner-image-lockfile/pnpm-lock.yaml" pnpm-lock.yaml + + - name: Free runner disk + run: | + set -euo pipefail + sudo apt-get clean || true + sudo rm -rf /usr/share/dotnet /usr/share/swift /usr/local/lib/android /usr/local/share/boost \ + /usr/local/share/powershell /opt/ghc /opt/hostedtoolcache/CodeQL /opt/hostedtoolcache/PyPy /opt/hostedtoolcache/Ruby || true + docker system prune -af || true + df -h + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4 + with: + buildkitd-config-inline: | + [registry."docker.io"] + mirrors = ["mirror.gcr.io"] + + # The build itself runs the frozen install, the Runner's own build, the + # provider pack integrity check and the layout check. The tree is + # exported for the checks below. + # + # This is the publication form of the build, the only one whose pack + # names the image (`runnerInputsDigest`), so the check below can bind + # the tree to the digest the identity job resolved. Nothing here + # publishes it: the tree stays on this runner. + - name: Build the Runner image + run: | + set -euo pipefail + docker buildx build \ + --target runner-artifacts \ + --platform "$PLATFORM" \ + --build-arg "PAPERCLIP_RUNNER_SOURCE_REVISION=$GITHUB_SHA" \ + --build-arg PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1 \ + --provenance=false --sbom=false \ + --output "type=local,dest=$RUNNER_TEMP/runner-image/tree" \ + . + + # Against the exported tree, bound to this run: the digest the identity + # job resolved, this commit and this leg's architecture. Checks every + # documented path, the build stamp, every pack artifact and tree digest + # in provider-pack.json, and every transport archive. It also extracts + # the archives as a sandbox does and compares the result with the pack; + # that needs about as much free disk as the pack is large. + - name: Check the layout contract and pack integrity + run: | + node scripts/runner-image-layout.mjs check "$RUNNER_TEMP/runner-image/tree" \ + --expect-inputs-digest "$DIGEST" \ + --expect-source-revision "$GITHUB_SHA" \ + --expect-architecture "$ARCH" + + - name: Run the daemon on every consumer base image + run: | + docker buildx build \ + --file docker/runner-image/Dockerfile.smoke \ + --platform "$PLATFORM" \ + --build-context "runner-artifacts=$RUNNER_TEMP/runner-image/tree" \ + --output "type=local,dest=$RUNNER_TEMP/runner-image/smoke" \ + docker/runner-image + ls -l "$RUNNER_TEMP/runner-image/smoke" diff --git a/Dockerfile b/Dockerfile index b7e150b4d1a..f4905a76709 100644 --- a/Dockerfile +++ b/Dockerfile @@ -190,6 +190,185 @@ RUN mkdir -p /provider-pack-large \ && find . -type f -size +1048575c -exec sh -c 'mkdir -p "/provider-pack-large/$(dirname "$1")" && mv "$1" "/provider-pack-large/$1"' _ {} \; \ && find /provider-pack-large -exec touch -h -d @0 {} + +# Runner image (`--target runner-artifacts`). +# +# The stages below build the Runner once, from its own inputs only, as a plain +# file tree: the daemon, the Runner package's build output with its build +# stamp, the remote provider pack with its transport archives, and the few +# source files a sandbox image reads. The tree is the image +# ghcr.io/paperclipai/paperclip-runner, named `inputs-` after its +# inputs. doc/runner-image-contract.md is the contract; +# scripts/runner-image-layout.mjs and scripts/runner-image-identity.mjs +# enforce it. +# +# These stages are independent of every stage above. They install with a +# filtered, frozen lockfile and never read the server, the UI or the `deps` +# stage, so a change outside the Runner's inputs leaves them cached, and the +# default targets never build them. +# +# Consumers must only `COPY --from=runner-artifacts `. A build can then +# replace the stage with an image built earlier: +# --build-context runner-artifacts=docker-image://ghcr.io/paperclipai/paperclip-runner@sha256: +# +# The image identity is a digest of this whole file and of every file under +# the paths `runner-artifacts-context` copies. A test +# (runner-image-identity.test.ts) holds the three rules that make that enough: +# every base image of these stages is pinned by digest, only +# `runner-artifacts-context` reads the build context, and it copies only paths +# in RUNNER_IMAGE_CONTEXT_INPUTS (scripts/runner-image-identity.mjs). + +# The Runner's inputs, exactly as the build context supplies them (after +# .dockerignore). Later stages copy from here, so each one is keyed by the +# content of the paths it reads and by nothing else in the repository. +FROM scratch AS runner-artifacts-context +COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc tsconfig.base.json / +COPY patches /patches +COPY scripts/create-provider-pack-archive.mjs scripts/link-plugin-dev-sdk.mjs scripts/runner-image-identity.mjs scripts/runner-image-layout.mjs /scripts/ +COPY packages/paperclip-eval-kernel /packages/paperclip-eval-kernel +COPY packages/paperclip-runner /packages/paperclip-runner +# build:typescript checks the Runner's generated provider-failure contract +# against this copy, which @paperclipai/shared owns. +COPY packages/shared/src/provider-failure.generated.ts /packages/shared/src/ + +# Debian bookworm is the oldest glibc any consumer runs, so a daemon compiled +# here also runs on trixie. The pack copies this Node binary as its own +# interpreter, which is why the exact Node release is pinned and part of the +# image identity. The digest is the multi-platform index (amd64 and arm64). +FROM node:24.22.3-bookworm@sha256:9d266751ca3d7fdbe651c878ffd5ad0a42fed49a18c283509267c97f025b7496 AS runner-artifacts-node +RUN corepack enable + +# The image identity, computed inside the build from the files the build +# actually receives. `--target runner-artifacts-identity` exports it alone, so +# CI can read the digest before it builds. The Dockerfile is copied here +# only: the identity covers its text. +FROM runner-artifacts-node AS runner-artifacts-identity-compute +WORKDIR /workspace +COPY --from=runner-artifacts-context / ./ +COPY Dockerfile ./ +RUN node scripts/runner-image-identity.mjs --json > /runner-image-identity.json + +FROM scratch AS runner-artifacts-identity +COPY --from=runner-artifacts-identity-compute /runner-image-identity.json /runner-image-identity.json + +# Same checksum-verified rustup as the `rust-toolchain` stage above, on the +# bookworm base. The compiler is the one packages/paperclip-runner/rust-toolchain.toml +# names. The base image supplies the C toolchain. +FROM runner-artifacts-node AS runner-artifacts-toolchain +# cargo strips the release binary itself. The Runner's build stamp records the +# size of every file under dist, so the binary must not change after the build. +ENV RUSTUP_HOME=/usr/local/rustup \ + CARGO_HOME=/usr/local/cargo \ + PATH=/usr/local/cargo/bin:$PATH \ + CARGO_PROFILE_RELEASE_STRIP=symbols +ARG RUSTUP_VERSION=1.29.0 +ARG RUSTUP_SHA256_AMD64=4acc9acc76d5079515b46346a485974457b5a79893cfb01112423c89aeb5aa10 +ARG RUSTUP_SHA256_ARM64=9732d6c5e2a098d3521fca8145d826ae0aaa067ef2385ead08e6feac88fa5792 +RUN set -eux; \ + arch="$(dpkg --print-architecture)"; \ + case "$arch" in \ + amd64) rustTarget="x86_64-unknown-linux-gnu"; sha256="$RUSTUP_SHA256_AMD64" ;; \ + arm64) rustTarget="aarch64-unknown-linux-gnu"; sha256="$RUSTUP_SHA256_ARM64" ;; \ + *) echo "unsupported architecture: $arch" >&2; exit 1 ;; \ + esac; \ + curl -fsSLo /tmp/rustup-init "https://static.rust-lang.org/rustup/archive/${RUSTUP_VERSION}/${rustTarget}/rustup-init"; \ + echo "${sha256} /tmp/rustup-init" | sha256sum -c -; \ + chmod +x /tmp/rustup-init; \ + /tmp/rustup-init -y --no-modify-path --profile minimal --default-toolchain none; \ + rm /tmp/rustup-init +COPY --from=runner-artifacts-context /packages/paperclip-runner/rust-toolchain.toml /tmp/runner-toolchain/rust-toolchain.toml +RUN cd /tmp/runner-toolchain && rustup toolchain install && rustc --version + +# Compile the daemon from the files Cargo reads, so a TypeScript-only change +# reuses this layer. The Runner's own build below runs the same cargo command +# and finds the target current. +FROM runner-artifacts-toolchain AS runner-artifacts-runnerd +WORKDIR /workspace/packages/paperclip-runner +COPY --from=runner-artifacts-context /packages/paperclip-runner/rust-toolchain.toml ./ +COPY --from=runner-artifacts-context /packages/paperclip-runner/runner ./runner +COPY --from=runner-artifacts-context /packages/paperclip-runner/protocol ./protocol +COPY --from=runner-artifacts-context /packages/paperclip-runner/acpx-profiles.json /packages/paperclip-runner/antigravity-distributions.json ./ +# Cargo fingerprints source mtimes; see the `runner-build` stage above. +RUN find runner protocol -type f -exec touch -d @0 {} + \ + && touch -d @0 rust-toolchain.toml acpx-profiles.json antigravity-distributions.json \ + && cargo build --release --manifest-path runner/Cargo.toml --locked -p paperclip-runner-core --bin paperclip-runnerd + +FROM runner-artifacts-runnerd AS runner-artifacts-build +WORKDIR /workspace +COPY --from=runner-artifacts-context / ./ +COPY --from=runner-artifacts-identity /runner-image-identity.json /runner-image-identity.json +# The source revision is provenance, not identity: the commit whose build +# produced this image. PAPERCLIP_BUILD_COMMIT is the fallback so one argument +# stamps a whole `docker build`. Without either, the tree has the daemon and +# the Runner build but no provider pack, as in the `runner-provider-pack` stage. +ARG PAPERCLIP_RUNNER_SOURCE_REVISION="" +ARG PAPERCLIP_BUILD_COMMIT="" +# Set to 1 only by the workflow that builds the image for publication. Only +# then does the pack record `runnerInputsDigest`, the name of the published +# image. Another image build that runs this stage inline, with +# PAPERCLIP_BUILD_COMMIT, builds the same Runner but must not claim to be it. +ARG PAPERCLIP_RUNNER_IMAGE_PUBLICATION="" +# One layer: the install tree and the pnpm store are removed before the layer +# is committed, and the pack is granted a+rX in the layer that writes it (see +# the `runner-provider-pack` stage above for why). +# +# The Runner is built with its own scripts, in the order its `build` script +# runs them: the two steps that write build output, between the two that record +# the build stamp. The stamp lets a later build reuse this output +# (server/scripts/prepare-runner-vendor.mjs). The other steps of `build` are +# drift checks that compare committed files across the repository; they write +# nothing, they need files outside the Runner's inputs, and repository CI runs +# them on every pull request. A test fails when `build` gains a step, so that +# a new output step cannot be missed here. +# +# The install is frozen: the identity above covers pnpm-lock.yaml as the build +# received it, and resolving again here would build from a lockfile the +# identity never saw. +RUN set -eu; \ + revision="${PAPERCLIP_RUNNER_SOURCE_REVISION:-${PAPERCLIP_BUILD_COMMIT}}"; \ + publication="${PAPERCLIP_RUNNER_IMAGE_PUBLICATION}"; \ + case "$publication" in ""|1) ;; *) echo "ERROR: PAPERCLIP_RUNNER_IMAGE_PUBLICATION must be 1 or unset" >&2; exit 1 ;; esac; \ + if [ -n "$publication" ] && [ -z "$revision" ]; then echo "ERROR: a publication build needs PAPERCLIP_RUNNER_SOURCE_REVISION" >&2; exit 1; fi; \ + find packages/paperclip-runner/runner packages/paperclip-runner/protocol -type f -exec touch -d @0 {} +; \ + touch -d @0 packages/paperclip-runner/rust-toolchain.toml packages/paperclip-runner/acpx-profiles.json packages/paperclip-runner/antigravity-distributions.json; \ + pnpm install --frozen-lockfile --filter '@paperclipai/paperclip-runner...' || { \ + echo "ERROR: the frozen install failed. If pnpm reported ERR_PNPM_OUTDATED_LOCKFILE, the committed pnpm-lock.yaml is behind the Runner's manifests. The repository's lockfile refresh fixes that on master. For a local build only, resolve it first: pnpm install --resolution-only --ignore-scripts --no-frozen-lockfile" >&2; \ + exit 1; \ + }; \ + cd packages/paperclip-runner; \ + node scripts/record-build-inputs.mjs --begin; \ + pnpm run build:typescript; \ + pnpm run build:binary; \ + node scripts/record-build-inputs.mjs --finish; \ + cd /workspace; \ + mkdir -p /out; \ + if [ -n "$revision" ]; then \ + if [ -n "$publication" ]; then \ + PAPERCLIP_RUNNER_INPUTS_DIGEST="$(node -p 'require("/runner-image-identity.json").digest')"; \ + export PAPERCLIP_RUNNER_INPUTS_DIGEST; \ + fi; \ + PAPERCLIP_RUNNER_SOURCE_REVISION="$revision" node packages/paperclip-runner/scripts/build-provider-pack.mjs /out/provider-pack; \ + node scripts/create-provider-pack-archive.mjs /out/provider-pack; \ + node_modules/.bin/esbuild /out/provider-pack/dist/live/runnerd-codex-transport.js \ + --bundle --platform=node --format=esm --log-level=warning \ + --banner:js='import { createRequire as paperclipCreateRequire } from "node:module"; const require = paperclipCreateRequire(import.meta.url);' \ + --outfile=/out/bundles/runnerd-codex-transport.mjs; \ + node scripts/runner-image-layout.mjs write --out /out --workspace /workspace --identity /runner-image-identity.json --source-revision "$revision" ${publication:+--publication}; \ + chmod -R a+rX /out; \ + node scripts/runner-image-layout.mjs check /out --expect-source-revision "$revision" ${publication:+--expect-inputs-digest "$PAPERCLIP_RUNNER_INPUTS_DIGEST"}; \ + cd / && /out/provider-pack/node_modules/node/bin/node --input-type=module -e 'const transport = await import("/out/bundles/runnerd-codex-transport.mjs"); if (typeof transport.createCapabilityRunnerdCodexTransport !== "function") process.exit(1);'; \ + else \ + echo "Skipping the provider pack: supply a full PAPERCLIP_RUNNER_SOURCE_REVISION or PAPERCLIP_BUILD_COMMIT to build a complete Runner image"; \ + node scripts/runner-image-layout.mjs write --out /out --workspace /workspace --identity /runner-image-identity.json; \ + chmod -R a+rX /out; \ + node scripts/runner-image-layout.mjs check /out --allow-unstamped; \ + fi; \ + /out/paperclip-runnerd --build-metadata > /dev/null; \ + cd /; \ + rm -rf /workspace /root/.local/share/pnpm /root/.cache + +FROM scratch AS runner-artifacts +COPY --from=runner-artifacts-build /out/ / + FROM base AS production ARG USER_UID=1000 ARG USER_GID=1000 diff --git a/doc/DOCKER.md b/doc/DOCKER.md index 3c3cf90e04d..f487b3a0c86 100644 --- a/doc/DOCKER.md +++ b/doc/DOCKER.md @@ -77,6 +77,16 @@ Downstream deployment tooling must verify [source proof](cloud-build-readiness.m the standard image attestation, the exact-source migrator, and its own composed image before rollout. Resolve immutable digests instead of deploying mutable tags. +## Runner image + +The `runner-artifacts` target builds the Runner alone: the daemon, the Runner +package's build output, the remote provider pack and its transport archives. +It does not depend on the server or UI build, and no other target depends on +it yet. `.github/workflows/runner-image.yml` builds and checks it on pull +requests, for Linux AMD64 and ARM64. See +[`doc/runner-image-contract.md`](runner-image-contract.md) for the layout, the +identity rules and how to consume the image. + ## One-liner (build + run) ```sh diff --git a/doc/runner-image-contract.md b/doc/runner-image-contract.md new file mode 100644 index 00000000000..9166512b91e --- /dev/null +++ b/doc/runner-image-contract.md @@ -0,0 +1,127 @@ +# Runner image contract + +The Runner image is the Runner built alone, as a plain file tree with no +entrypoint and no operating system: the `runner-artifacts` target of the +`Dockerfile`. An image build copies paths out of it instead of compiling the +Runner again. Its name is `ghcr.io/paperclipai/paperclip-runner`. Nothing in +this repository consumes it yet. + +Nothing publishes it yet: `.github/workflows/runner-image.yml` builds and +checks it. + +## Layout + +Every path a consumer may copy (`RUNNER_IMAGE_PATHS` in +`scripts/runner-image-layout.mjs`). Every file is readable by every user. + +| Path | Content | +| --- | --- | +| `/runner-image.json` | Identity and description of this image. | +| `/paperclip-runnerd` | The daemon. A stripped release binary, mode `0755`. | +| `/provider-pack/` | The remote provider pack, with `provider-pack.json`. | +| `/provider-pack.archive.json` | Receipt of the pack's transport archives. | +| `/provider-pack.archives/` | The transport archives the receipt lists. | +| `/runner-package/package.json` | The Runner package manifest. | +| `/runner-package/dist/` | The Runner's complete build output. `dist/bin/paperclip-runnerd` is the same file as `/paperclip-runnerd`. | +| `/runner-package/node_modules/.cache/paperclip-runner-build-inputs.json` | The build stamp the Runner's build recorded for that output. | +| `/runner-package/scripts/provision-grok.mjs` | Provisions the native Grok executable. Reads `platforms.json` by relative path. | +| `/runner-package/src/providers/grok/platforms.json` | The Grok release pins. | +| `/runner-package/src/live/runnerd-codex-transport.ts` | The transport source, as a contract file. It defines `RUNNER_CLIENT_VERSION`. | +| `/bundles/runnerd-codex-transport.mjs` | The pack's `dist/live/runnerd-codex-transport.js` as one module. It imports without `node_modules`. | +| `/pnpm-lock.yaml` | The lockfile the image was installed from. | + +Paths under `/runner-package/` keep their place inside +`packages/paperclip-runner`. `runner-image.json` describes one platform: + +- `inputsDigest` (the identity below) and `buildInputsDigest` (the digest in + the Runner's build stamp); +- `sourceRevision`: the commit given to the build, also in the pack as + `payload.runnerSourceRevision`; +- `publication`: `true` only for a build with the build argument + `PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1`. Only then does the pack carry the + identity, as `payload.runnerInputsDigest`. Another image build that runs + the stage inline builds the same Runner but is not this image; +- `platform` (`linux`, `amd64` or `arm64`) and `libc`: the glibc the daemon + was compiled on (Debian bookworm, the oldest a consumer runs) and the + newest glibc version it needs; +- `providerPack`: the pack's digest and target; +- `paths` and `sha256`: the table above, and the digest of every single file. + +## Identity + +An image is named `inputs-`. `scripts/runner-image-identity.mjs` +computes the digest from: + +- every file under the paths the build copies from the build context + (`RUNNER_IMAGE_CONTEXT_INPUTS`, which include `pnpm-lock.yaml`): path, + executable bit and content, and each symbolic link by its target; +- the whole `Dockerfile`: the recipe, the base image pinned by digest and the + toolchain pins. Any edit to it makes a new image; +- the two platforms, `linux/amd64` and `linux/arm64`. + +The source revision is not part of it, and neither is the text of +`.dockerignore`: a rule changes the digest only when it changes which of +those files the build receives. The build computes the digest for itself: + +```sh +docker buildx build --target runner-artifacts-identity --output type=local,dest=/tmp/identity . +jq -r .digest /tmp/identity/runner-image-identity.json +``` + +The install is frozen. It fails when the lockfile is behind the manifests the +build reads (the root one, `packages/paperclip-runner` and +`packages/paperclip-eval-kernel`). A contributor cannot edit the lockfile, so +pull-request runs resolve it first. For a local build, run +`pnpm install --resolution-only --ignore-scripts --no-frozen-lockfile`. + +## Checks + +`node scripts/runner-image-layout.mjs check ` runs in the build and +again on the exported tree. It fails unless: + +- every documented path exists, matches its digest in `runner-image.json`, + and resolves inside the tree; +- the build stamp names the inputs the identity names; +- every artifact in `provider-pack.json` has its digest, the `dist` tree and + each provider asset tree match their tree digests, and the pack names this + image's revision and platform; +- the pack names the inputs digest in a publication build and in no other. + `--expect-inputs-digest` fails on any other build; +- every transport archive matches its receipt, and the archives + extract to the pack. The check extracts them as a sandbox does (GNU tar + with the options in `provider-pack-layers.ts`) and compares paths, content, + link targets and all twelve permission bits, after the `a+rX` grant the + build makes once the archives are written. + +The build also runs `paperclip-runnerd --build-metadata` on every base image +in `docker/runner-image/Dockerfile.smoke`. Add a base there before a consumer +uses it. + +## Consuming the image + +Read the image only with `COPY --from`, and pin it by digest: + +```dockerfile +FROM ghcr.io/paperclipai/paperclip-runner@sha256: AS runner-artifacts +FROM debian:trixie-slim +COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd +``` + +A Dockerfile with a `runner-artifacts` stage of its own, as in this +repository, can take a built image or tree in its place with +`--build-context runner-artifacts=`. The stage is then +not built. + +## Known limits + +- A build without `PAPERCLIP_RUNNER_SOURCE_REVISION` or + `PAPERCLIP_BUILD_COMMIT` has no pack. It is for local use. +- The build runs the steps of the Runner's `build` script that write output, + not its drift checks; repository CI runs those. +- A build that vendors `/runner-package/` reuses `dist` only when its own + Runner build-inputs digest equals the stamp's. The image computes that + digest in the `.dockerignore`-filtered context; a checkout gives another. +- `# syntax=docker/dockerfile:1.20` is a tag. A new frontend release under it + does not change the identity. +- The archive check does not tell a directory with its own archive member + from one created only as a file's parent. diff --git a/docker/runner-image/Dockerfile.smoke b/docker/runner-image/Dockerfile.smoke new file mode 100644 index 00000000000..b4dbbbbc038 --- /dev/null +++ b/docker/runner-image/Dockerfile.smoke @@ -0,0 +1,64 @@ +# syntax=docker/dockerfile:1.20 +# Smoke matrix for the Runner image (doc/runner-image-contract.md). +# +# Runs the daemon from a built Runner image on every base image a consumer +# puts it on, so a libc or loader mismatch fails the Runner build and not a +# consumer's build. Supply the image as the `runner-artifacts` build context: +# +# docker buildx build -f docker/runner-image/Dockerfile.smoke \ +# --build-context runner-artifacts= \ +# docker/runner-image +# +# The stages read only `COPY --from=runner-artifacts `, which is the +# consumer contract. Each base is pinned by its multi-platform index digest so +# the same file runs natively on amd64 and arm64. These pins are not part of +# the Runner image identity: they change what is tested, not what is built. + +FROM debian:bookworm-slim@sha256:734a72b3d6142a71993b4bc580ca01d8ca687f77a2c422d96a961d3376b179bc AS smoke-debian-bookworm-slim +COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd +RUN paperclip-runnerd --build-metadata > /tmp/runnerd-metadata.json \ + && grep -q '"paperclip-runner/runnerd-build-metadata/v1"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_ws_loopback"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_wss"' /tmp/runnerd-metadata.json \ + && grep -q '"listen_ws"' /tmp/runnerd-metadata.json + +FROM debian:trixie-slim@sha256:a72b4433de1cf7d6bae0c4cee74d0547f58601a643b3375f070c51600d63b6b2 AS smoke-debian-trixie-slim +COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd +RUN paperclip-runnerd --build-metadata > /tmp/runnerd-metadata.json \ + && grep -q '"paperclip-runner/runnerd-build-metadata/v1"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_ws_loopback"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_wss"' /tmp/runnerd-metadata.json \ + && grep -q '"listen_ws"' /tmp/runnerd-metadata.json + +FROM node:24-trixie-slim@sha256:af02d57b57719b9657a45199a79264a9437940cd55b3c7b3fc99615654f124a0 AS smoke-node-24-trixie-slim +COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd +RUN paperclip-runnerd --build-metadata > /tmp/runnerd-metadata.json \ + && grep -q '"paperclip-runner/runnerd-build-metadata/v1"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_ws_loopback"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_wss"' /tmp/runnerd-metadata.json \ + && grep -q '"listen_ws"' /tmp/runnerd-metadata.json + +FROM python:3.13-slim-trixie@sha256:e48f59cdba69a3cbd9ed2cf0f348d90d45a8d350d98134cf1070bc106ee9ed90 AS smoke-python-3.13-slim-trixie +COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd +RUN paperclip-runnerd --build-metadata > /tmp/runnerd-metadata.json \ + && grep -q '"paperclip-runner/runnerd-build-metadata/v1"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_ws_loopback"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_wss"' /tmp/runnerd-metadata.json \ + && grep -q '"listen_ws"' /tmp/runnerd-metadata.json + +FROM daytonaio/sandbox:0.8.0@sha256:edb66f95f2f09a28a029a0e03d516cf5482ef13a218e93ab1d80954f6ee7ebbb AS smoke-daytonaio-sandbox-0.8.0 +COPY --from=runner-artifacts /paperclip-runnerd /usr/local/bin/paperclip-runnerd +RUN paperclip-runnerd --build-metadata > /tmp/runnerd-metadata.json \ + && grep -q '"paperclip-runner/runnerd-build-metadata/v1"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_ws_loopback"' /tmp/runnerd-metadata.json \ + && grep -q '"dial_wss"' /tmp/runnerd-metadata.json \ + && grep -q '"listen_ws"' /tmp/runnerd-metadata.json + +# The default target. It copies one result from every base, so building it +# runs the whole matrix. +FROM scratch AS smoke +COPY --from=smoke-debian-bookworm-slim /tmp/runnerd-metadata.json /debian-bookworm-slim.json +COPY --from=smoke-debian-trixie-slim /tmp/runnerd-metadata.json /debian-trixie-slim.json +COPY --from=smoke-node-24-trixie-slim /tmp/runnerd-metadata.json /node-24-trixie-slim.json +COPY --from=smoke-python-3.13-slim-trixie /tmp/runnerd-metadata.json /python-3.13-slim-trixie.json +COPY --from=smoke-daytonaio-sandbox-0.8.0 /tmp/runnerd-metadata.json /daytonaio-sandbox-0.8.0.json diff --git a/packages/paperclip-runner/scripts/build-provider-pack.mjs b/packages/paperclip-runner/scripts/build-provider-pack.mjs index 7d9ed8ae768..e68ec58baf5 100644 --- a/packages/paperclip-runner/scripts/build-provider-pack.mjs +++ b/packages/paperclip-runner/scripts/build-provider-pack.mjs @@ -10,7 +10,6 @@ import { mkdtempSync, readdirSync, readFileSync, - readlinkSync, realpathSync, renameSync, rmSync, @@ -24,7 +23,7 @@ import { parseProviderPackArguments, materializeCandidateProviderPack, providerP import { smokeKimiProviderPack } from "./kimi-provider-pack-smoke.mjs"; import { buildNodeStartupTimeout } from "./build-node-startup-timeout.mjs"; import { writePortableExecutableShim, writePortableCopilotShims } from "./provider-pack-executable-shims.mjs"; -import { providerPackLibc, removeControllerArtifactsFromProviderPack, removeForeignLibcPackagesFromProviderPack } from "./provider-pack-runtime-tree.mjs"; +import { providerPackLibc, removeControllerArtifactsFromProviderPack, removeForeignLibcPackagesFromProviderPack, sha256Tree } from "./provider-pack-runtime-tree.mjs"; import { packContractDigest } from "./contracts/contract-fingerprints.mjs"; const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), ".."); @@ -62,35 +61,6 @@ function sha256File(path) { .digest("hex")}`; } -function sha256Tree(root) { - const hash = createHash("sha256"); - const visit = (directory, prefix = "") => { - const entries = readdirSync(directory, { withFileTypes: true }).sort( - (left, right) => left.name.localeCompare(right.name), - ); - for (const entry of entries) { - const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name; - const absolutePath = join(directory, entry.name); - if (entry.isDirectory()) { - hash.update(`directory\0${relativePath}\n`); - visit(absolutePath, relativePath); - } else if (entry.isFile()) { - hash.update(`file\0${relativePath}\0${sha256File(absolutePath)}\n`); - } else if (entry.isSymbolicLink()) { - hash.update( - `symlink\0${relativePath}\0${readlinkSync(absolutePath)}\n`, - ); - } else { - throw new Error( - `Provider pack tree contains unsupported entry ${relativePath}`, - ); - } - } - }; - visit(root); - return `sha256:${hash.digest("hex")}`; -} - function writePortableNodeShim(name, entrypoint) { const shimPath = join(temporaryRoot, "node_modules", ".bin", name); writeFileSync( diff --git a/packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs b/packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs index 39248ce8e2a..c053a3c7e98 100644 --- a/packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs +++ b/packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs @@ -1,6 +1,43 @@ +import { createHash } from "node:crypto"; import { existsSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmdirSync, rmSync, unlinkSync } from "node:fs"; import { basename, dirname, join, relative, resolve, sep } from "node:path"; +/** + * The digest the pack manifest records for a directory tree: `distDigest` and + * each provider asset tree. The server recomputes it with the same walk + * (remote-provider-pack-verification.ts), so the entry order and the record + * format are part of the pack contract. + */ +export function sha256Tree(root) { + const hash = createHash("sha256"); + const visit = (directory, prefix = "") => { + const entries = readdirSync(directory, { withFileTypes: true }).sort( + (left, right) => left.name.localeCompare(right.name), + ); + for (const entry of entries) { + const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name; + const absolutePath = join(directory, entry.name); + if (entry.isDirectory()) { + hash.update(`directory\0${relativePath}\n`); + visit(absolutePath, relativePath); + } else if (entry.isFile()) { + const file = createHash("sha256").update(readFileSync(absolutePath)).digest("hex"); + hash.update(`file\0${relativePath}\0sha256:${file}\n`); + } else if (entry.isSymbolicLink()) { + hash.update( + `symlink\0${relativePath}\0${readlinkSync(absolutePath)}\n`, + ); + } else { + throw new Error( + `Provider pack tree contains unsupported entry ${relativePath}`, + ); + } + } + }; + visit(root); + return `sha256:${hash.digest("hex")}`; +} + export function removeControllerArtifactsFromProviderPack(packRoot) { for (const directory of ["bin", "remote-provider-packs"]) { rmSync(join(packRoot, "dist", directory), { recursive: true, force: true }); diff --git a/packages/paperclip-runner/scripts/provider-pack-runtime-tree.test.mjs b/packages/paperclip-runner/scripts/provider-pack-runtime-tree.test.mjs index 600163d7a8d..c55860d9c68 100644 --- a/packages/paperclip-runner/scripts/provider-pack-runtime-tree.test.mjs +++ b/packages/paperclip-runner/scripts/provider-pack-runtime-tree.test.mjs @@ -8,8 +8,27 @@ import { removeControllerArtifactsFromProviderPack, removeForeignLibcPackagesFromProviderPack, removePnpmStoreEntries, + sha256Tree, } from "./provider-pack-runtime-tree.mjs"; +test("the tree digest of a pack directory keeps its recorded format", () => { + // Packs already in images carry digests computed this way, and the server + // recomputes them with its own copy of the walk. A change here must be a + // deliberate pack contract change. + const root = mkdtempSync(join(tmpdir(), "provider-pack-tree-digest-")); + try { + mkdirSync(join(root, "cli"), { recursive: true }); + writeFileSync(join(root, "index.js"), "export {};\n"); + writeFileSync(join(root, "cli", "proxy.cjs"), "module.exports = {};\n"); + symlinkSync("index.js", join(root, "main.js")); + assert.equal(sha256Tree(root), "sha256:01f41c32adc4fae6f04481df39bb22ef6facf49424b8fb77a31d555fd7ff8878"); + writeFileSync(join(root, "cli", "proxy.cjs"), "module.exports = { changed: true };\n"); + assert.notEqual(sha256Tree(root), "sha256:01f41c32adc4fae6f04481df39bb22ef6facf49424b8fb77a31d555fd7ff8878"); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + test("image and native producer packs retain identical provider outputs despite different controller artifacts", () => { const root = mkdtempSync(join(tmpdir(), "provider-pack-producers-")); try { diff --git a/scripts/runner-image-identity.mjs b/scripts/runner-image-identity.mjs new file mode 100644 index 00000000000..83879adc88a --- /dev/null +++ b/scripts/runner-image-identity.mjs @@ -0,0 +1,166 @@ +#!/usr/bin/env node +// Identity of the Runner image (ghcr.io/paperclipai/paperclip-runner). +// +// The Runner image is built once for each distinct set of inputs and named +// `inputs-`. This script computes that digest. It covers: +// - the context tree: every file under the paths the build copies from the +// build context, by path, executable bit and content, and every symbolic +// link by its target. Nothing under those paths is skipped; +// - the whole Dockerfile. The recipe stages, the pinned base images and the +// toolchain pins are text in it, so they need no separate treatment. Any +// edit to the Dockerfile makes a new image; +// - the target platforms. +// +// It does not cover the source revision, so a commit that changes none of the +// above reuses the image an earlier commit built. It does not cover the text +// of .dockerignore: those rules only decide which files the build receives, +// and the context tree is hashed from the files it received. +// +// The digest that counts is the one the image build computes for itself: the +// `runner-artifacts-identity-compute` stage runs this script on the files the +// build context supplies after .dockerignore. Run in a checkout, the script +// also reads the files .dockerignore drops and anything a local build left +// behind, so it prints another digest. For the real one: +// +// docker buildx build --target runner-artifacts-identity --output type=local,dest=DIR . +// +// Usage: node scripts/runner-image-identity.mjs [--json] +// See doc/runner-image-contract.md. + +import { createHash } from "node:crypto"; +import { lstatSync, readdirSync, readFileSync, readlinkSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { computeBuildInputsDigest } from "../packages/paperclip-runner/scripts/build-inputs.mjs"; +import { RUNNER_IMAGE_INPUTS_SCHEMA } from "./runner-image-layout.mjs"; + +export { RUNNER_IMAGE_INPUTS_SCHEMA }; +export const RUNNER_IMAGE_NAME = "ghcr.io/paperclipai/paperclip-runner"; +export const RUNNER_IMAGE_DOCKERFILE = "Dockerfile"; +export const RUNNER_IMAGE_PLATFORMS = Object.freeze(["linux/amd64", "linux/arm64"]); + +/** + * Every path the `runner-artifacts-context` stage may copy from the build + * context. A test checks that the stage copies nothing else and that no other + * Runner stage reads the build context. + * + * @paperclipai/shared owns the generated file. build:typescript only checks + * the Runner's own copy against it, but it fails without it. + */ +export const RUNNER_IMAGE_CONTEXT_INPUTS = Object.freeze([ + ".npmrc", + "package.json", + "packages/paperclip-eval-kernel", + "packages/paperclip-runner", + "packages/shared/src/provider-failure.generated.ts", + "patches", + "pnpm-lock.yaml", + "pnpm-workspace.yaml", + "scripts/create-provider-pack-archive.mjs", + "scripts/link-plugin-dev-sdk.mjs", + "scripts/runner-image-identity.mjs", + "scripts/runner-image-layout.mjs", + "tsconfig.base.json", +]); + +function fail(message) { + throw new Error(`Runner image identity: ${message}`); +} + +function record(hash, kind, ...fields) { + hash.update(kind); + for (const field of fields) { + hash.update("\0"); + hash.update(field); + } + hash.update("\n"); +} + +const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex"); +const compareNames = (left, right) => (left < right ? -1 : left > right ? 1 : 0); + +/** + * Digest of everything under the context inputs, as the tree at `repoRoot` + * holds it. Each file is recorded by path, executable bit and content digest, + * each symbolic link by its target, each directory by path. Entries are + * ordered by code unit, so the result does not depend on locale. + * @param {string} repoRoot + */ +export function computeContextTreeDigest(repoRoot) { + const hash = createHash("sha256"); + let fileCount = 0; + let byteCount = 0; + const visit = (relative, top) => { + const absolute = path.join(repoRoot, ...relative.split("/")); + let stat; + try { + stat = lstatSync(absolute); + } catch { + fail(`the build reads ${relative}, which is missing from the build context`); + } + if (stat.isSymbolicLink()) { + record(hash, "link", relative, readlinkSync(absolute)); + } else if (stat.isFile()) { + const content = readFileSync(absolute); + fileCount += 1; + byteCount += content.length; + record(hash, "file", relative, (stat.mode & 0o111) === 0 ? "-" : "x", sha256(content)); + } else if (stat.isDirectory()) { + const entries = readdirSync(absolute).sort(compareNames); + if (top && entries.length === 0) fail(`the build reads ${relative}, which is empty in the build context`); + record(hash, "directory", relative); + for (const name of entries) visit(`${relative}/${name}`, false); + } else { + fail(`the build reads ${relative}, which is not a file, a directory or a symbolic link`); + } + }; + for (const input of RUNNER_IMAGE_CONTEXT_INPUTS) visit(input, true); + return { digest: hash.digest("hex"), fileCount, byteCount }; +} + +/** + * The identity of the Runner image built from the tree at `repoRoot`. + * The Runner build-inputs digest is reported because the Runner's build stamp + * records it. It is not hashed again: the context tree covers its files. + * @param {string} repoRoot + */ +export function computeRunnerImageIdentity(repoRoot) { + const dockerfile = sha256(readFileSync(path.join(repoRoot, RUNNER_IMAGE_DOCKERFILE))); + const context = computeContextTreeDigest(repoRoot); + const buildInputs = computeBuildInputsDigest(repoRoot); + + const hash = createHash("sha256"); + record(hash, "schema", RUNNER_IMAGE_INPUTS_SCHEMA); + record(hash, "context", context.digest); + record(hash, "dockerfile", dockerfile); + for (const platform of RUNNER_IMAGE_PLATFORMS) record(hash, "platform", platform); + const digest = hash.digest("hex"); + + return { + schema: RUNNER_IMAGE_INPUTS_SCHEMA, + digest, + image: RUNNER_IMAGE_NAME, + tag: `inputs-${digest}`, + platforms: [...RUNNER_IMAGE_PLATFORMS], + context: { inputs: [...RUNNER_IMAGE_CONTEXT_INPUTS], ...context }, + dockerfile: { path: RUNNER_IMAGE_DOCKERFILE, sha256: dockerfile }, + buildInputs: { schema: buildInputs.schema, digest: buildInputs.digest }, + }; +} + +const invoked = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null; +if (invoked === import.meta.url) { + const flags = process.argv.slice(2); + if (flags.some((flag) => flag !== "--json")) { + process.stderr.write("Usage: node scripts/runner-image-identity.mjs [--json]\n"); + process.exit(2); + } + const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); + try { + const identity = computeRunnerImageIdentity(repoRoot); + process.stdout.write(flags.includes("--json") ? `${JSON.stringify(identity, null, 2)}\n` : `${identity.digest}\n`); + } catch (error) { + process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); + process.exit(1); + } +} diff --git a/scripts/runner-image-layout.mjs b/scripts/runner-image-layout.mjs new file mode 100644 index 00000000000..b1098914818 --- /dev/null +++ b/scripts/runner-image-layout.mjs @@ -0,0 +1,938 @@ +#!/usr/bin/env node +// Layout contract of the Runner image (ghcr.io/paperclipai/paperclip-runner). +// +// The image is a plain file tree with no entrypoint. Consumers copy paths out +// of it; RUNNER_IMAGE_PATHS is the complete list of paths they may copy, and +// runner-image.json at the root records it together with the image identity. +// doc/runner-image-contract.md is the prose form of this file. +// +// write runs inside the image build, after the Runner's own build. It +// places the Runner package's build output, its build stamp and the +// source files consumers read, then writes runner-image.json. The +// build has already put the provider pack, its archives and the +// transport bundle at their layout paths. +// check verifies a built tree: every documented path, runner-image.json, +// the build stamp, the provider pack's integrity and its transport +// archives. The image build runs it, and CI runs it again on the +// tree it exported. No checked path may resolve outside the tree. +// It also extracts the transport archives the way a sandbox does and +// compares the result with the provider pack, so an archive set that +// has the recorded bytes but not the pack's files does not pass. +// +// Usage: +// node scripts/runner-image-layout.mjs write --out DIR --workspace DIR --identity FILE +// [--source-revision SHA] [--publication] +// node scripts/runner-image-layout.mjs check DIR [--allow-unstamped] +// [--expect-inputs-digest HEX] [--expect-source-revision SHA] [--expect-architecture ARCH] +// An unknown flag, a repeated flag or a flag with an empty value is an error: +// an expectation that was not really given must not pass as one that held. +// --expect-inputs-digest also requires a publication build: only that build +// may say which published image it is. + +import { spawn, spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { once } from "node:events"; +import { + chmodSync, + createReadStream, + mkdtempSync, + readlinkSync, + rmSync, + copyFileSync, + cpSync, + existsSync, + lstatSync, + mkdirSync, + openSync, + readSync, + closeSync, + readFileSync, + readdirSync, + realpathSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { pipeline } from "node:stream/promises"; +import { pathToFileURL } from "node:url"; +import { createZstdDecompress } from "node:zlib"; +import { + BUILD_INPUTS_SCHEMA, + buildInputsStampPath, + expectedBuildOutputs, + findChangedBuildOutput, +} from "../packages/paperclip-runner/scripts/build-inputs.mjs"; +import { sha256Tree } from "../packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs"; + +export const RUNNER_IMAGE_SCHEMA = "paperclip.runner-image.v1"; +export const RUNNER_IMAGE_INPUTS_SCHEMA = "paperclip.runner-image-inputs.v1"; +export const PROVIDER_PACK_SCHEMA = "paperclip-runner/remote-provider-pack/v1"; +export const PROVIDER_PACK_ARCHIVE_SCHEMA = "paperclip-runner/provider-pack-archive/v2"; + +/** Every path a consumer may copy out of the image, relative to its root. */ +export const RUNNER_IMAGE_PATHS = Object.freeze({ + manifest: "runner-image.json", + runnerd: "paperclip-runnerd", + providerPack: "provider-pack", + providerPackManifest: "provider-pack/provider-pack.json", + providerPackArchiveReceipt: "provider-pack.archive.json", + providerPackArchives: "provider-pack.archives", + runnerPackage: "runner-package", + runnerPackageManifest: "runner-package/package.json", + runnerDist: "runner-package/dist", + runnerDistRunnerd: "runner-package/dist/bin/paperclip-runnerd", + runnerBuildStamp: "runner-package/node_modules/.cache/paperclip-runner-build-inputs.json", + grokProvisioner: "runner-package/scripts/provision-grok.mjs", + grokPlatforms: "runner-package/src/providers/grok/platforms.json", + runnerdCodexTransportContract: "runner-package/src/live/runnerd-codex-transport.ts", + runnerdCodexTransportBundle: "bundles/runnerd-codex-transport.mjs", + lockfile: "pnpm-lock.yaml", +}); + +const DIRECTORY_PATHS = new Set(["providerPack", "providerPackArchives", "runnerPackage", "runnerDist"]); +/** Paths that exist only when the build was given a source revision. */ +const STAMPED_ONLY_PATHS = new Set([ + "providerPackManifest", + "providerPackArchiveReceipt", + "providerPackArchives", + "runnerdCodexTransportBundle", +]); +const RUNNER_PACKAGE = "packages/paperclip-runner"; +/** + * Files `write` copies from the workspace, keyed by layout path. Everything + * under runner-package keeps its path inside the Runner package, so the tree + * can be laid over packages/paperclip-runner. + */ +const WORKSPACE_SOURCES = Object.freeze({ + runnerd: `${RUNNER_PACKAGE}/dist/bin/paperclip-runnerd`, + runnerPackageManifest: `${RUNNER_PACKAGE}/package.json`, + runnerBuildStamp: `${RUNNER_PACKAGE}/node_modules/.cache/paperclip-runner-build-inputs.json`, + grokProvisioner: `${RUNNER_PACKAGE}/scripts/provision-grok.mjs`, + grokPlatforms: `${RUNNER_PACKAGE}/src/providers/grok/platforms.json`, + runnerdCodexTransportContract: `${RUNNER_PACKAGE}/src/live/runnerd-codex-transport.ts`, + lockfile: "pnpm-lock.yaml", +}); + +/** OCI architecture name to the ELF machine and the Node architecture name of the pack. */ +const ARCHITECTURES = Object.freeze({ + amd64: { elfMachine: 62, node: "x64" }, + arm64: { elfMachine: 183, node: "arm64" }, +}); + +const HEX_64 = /^[0-9a-f]{64}$/; +const SHA256 = /^sha256:[0-9a-f]{64}$/; +const REVISION = /^[0-9a-f]{40}$/; +const VERSION = /^\d+\.\d+(?:\.\d+)?$/; + +export function canonicalJson(value) { + if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; + if (value && typeof value === "object") { + return `{${Object.keys(value) + .sort() + .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`) + .join(",")}}`; + } + return JSON.stringify(value); +} + +export function sha256File(file) { + const hash = createHash("sha256"); + const descriptor = openSync(file, "r"); + try { + const buffer = Buffer.allocUnsafe(1024 * 1024); + let read; + while ((read = readSync(descriptor, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, read)); + } finally { + closeSync(descriptor); + } + return `sha256:${hash.digest("hex")}`; +} + +function compareVersions(left, right) { + const a = left.split(".").map(Number); + const b = right.split(".").map(Number); + for (let index = 0; index < Math.max(a.length, b.length); index += 1) { + const difference = (a[index] ?? 0) - (b[index] ?? 0); + if (difference !== 0) return difference; + } + return 0; +} + +const resolveIn = (root, relative) => path.join(root, ...relative.split("/")); + +/** + * Where `relative` under `base` really is. A path that leaves `base`, by + * `..` or through a symbolic link, is "outside": hashing it would vouch for a + * file the image does not contain. + * @returns {{ state: "inside", path: string } | { state: "missing" } | { state: "outside" }} + */ +function locate(base, relative) { + const candidate = path.resolve(base, relative); + if (candidate !== base && !candidate.startsWith(`${base}${path.sep}`)) return { state: "outside" }; + let real; + let realBase; + try { + realBase = realpathSync(base); + real = realpathSync(candidate); + } catch { + return { state: "missing" }; + } + if (real !== realBase && !real.startsWith(`${realBase}${path.sep}`)) return { state: "outside" }; + return { state: "inside", path: real }; +} + +function readJson(file, problems, label) { + try { + return JSON.parse(readFileSync(file, "utf8")); + } catch (error) { + problems.push(`${label} is not readable JSON (${error instanceof SyntaxError ? "invalid JSON" : (error?.code ?? "unreadable")})`); + return null; + } +} + +/** The newest GLIBC symbol version the executable needs, read from its dynamic symbols. */ +export function requiredGlibcVersion(file) { + const result = spawnSync("objdump", ["-T", file], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); + if (result.status !== 0) throw new Error(`objdump could not read ${file}: ${String(result.stderr ?? result.error).trim()}`); + const versions = [...result.stdout.matchAll(/GLIBC_(\d+(?:\.\d+)+)/g)].map((match) => match[1]); + if (versions.length === 0) throw new Error(`${file} references no versioned glibc symbol`); + return versions.sort(compareVersions).at(-1); +} + +/** The platform and libc of the machine the image is being built on. */ +export function detectBuildEnvironment(runnerd) { + const architecture = Object.entries(ARCHITECTURES).find(([, value]) => value.node === process.arch)?.[0]; + const buildVersion = process.report?.getReport().header.glibcVersionRuntime; + if (process.platform !== "linux" || !architecture || !buildVersion) { + throw new Error("the Runner image is built on linux/amd64 or linux/arm64 with glibc"); + } + const release = Object.fromEntries(readFileSync("/etc/os-release", "utf8").split("\n") + .map((line) => /^([A-Z_]+)="?([^"]*)"?$/.exec(line)).filter(Boolean).map((match) => [match[1], match[2]])); + return { + platform: { os: "linux", architecture }, + libc: { + baseline: `${release.ID}-${release.VERSION_CODENAME || release.VERSION_ID}`, + buildVersion, + runnerdRequires: requiredGlibcVersion(runnerd), + }, + }; +} + +/** + * Places the daemon, the Runner package's build output with its stamp, and the + * source files consumers read, then writes runner-image.json. The provider + * pack, its archives and the transport bundle are already at their layout + * paths when the build has a source revision. + * @param {{ + * outRoot: string, + * workspaceRoot: string, + * identity: { schema: string, digest: string, buildInputs: { schema: string, digest: string } }, + * platform: { os: string, architecture: string }, + * libc: { baseline: string, buildVersion: string, runnerdRequires: string }, + * sourceRevision?: string | null, + * publication?: boolean, + * }} input + */ +export function writeRunnerImageManifest({ + outRoot, + workspaceRoot, + identity, + platform, + libc, + sourceRevision = null, + publication = false, +}) { + if (platform?.os !== "linux" || !ARCHITECTURES[platform?.architecture]) { + throw new Error(`Runner image supports linux/amd64 and linux/arm64, not ${JSON.stringify(platform)}`); + } + if (sourceRevision !== null && !REVISION.test(sourceRevision)) throw new Error("source revision must be a full Git SHA"); + if (publication && sourceRevision === null) throw new Error("a publication build needs a source revision"); + if (identity?.schema !== RUNNER_IMAGE_INPUTS_SCHEMA || !HEX_64.test(identity?.digest ?? "") + || identity?.buildInputs?.schema !== BUILD_INPUTS_SCHEMA || !HEX_64.test(identity?.buildInputs?.digest ?? "")) { + throw new Error("identity must be the output of scripts/runner-image-identity.mjs --json"); + } + for (const key of ["buildVersion", "runnerdRequires"]) { + if (!VERSION.test(libc?.[key] ?? "")) throw new Error(`libc ${key} must be a version number`); + } + if (typeof libc.baseline !== "string" || !/^[a-z0-9][a-z0-9.-]*$/.test(libc.baseline)) { + throw new Error("libc baseline must name the distribution release the daemon was compiled on"); + } + + // The Runner's build records its stamp only when its inputs did not change + // while it ran. Never write one here: a missing stamp means the build output + // cannot be trusted to match the identity. + const stampSource = resolveIn(workspaceRoot, WORKSPACE_SOURCES.runnerBuildStamp); + if (!existsSync(stampSource)) { + throw new Error("the Runner build recorded no build stamp; run `pnpm --filter @paperclipai/paperclip-runner build` first"); + } + const stamp = JSON.parse(readFileSync(stampSource, "utf8")); + if (stamp.digest !== identity.buildInputs.digest) { + throw new Error( + `the Runner was built from inputs ${stamp.digest}, but the image identity was computed from ${identity.buildInputs.digest}`, + ); + } + + const place = (source, relative, mode) => { + const target = resolveIn(outRoot, relative); + mkdirSync(path.dirname(target), { recursive: true, mode: 0o755 }); + copyFileSync(source, target); + chmodSync(target, mode); + }; + mkdirSync(outRoot, { recursive: true, mode: 0o755 }); + // dist first: the stamp records the size of every file under it. + cpSync(resolveIn(workspaceRoot, `${RUNNER_PACKAGE}/dist`), resolveIn(outRoot, RUNNER_IMAGE_PATHS.runnerDist), { + recursive: true, + verbatimSymlinks: true, + }); + for (const [name, source] of Object.entries(WORKSPACE_SOURCES)) { + place(resolveIn(workspaceRoot, source), RUNNER_IMAGE_PATHS[name], name === "runnerd" ? 0o755 : 0o644); + } + // An unstamped build has no pack. Keep the directory so the path still exists. + mkdirSync(resolveIn(outRoot, RUNNER_IMAGE_PATHS.providerPack), { recursive: true, mode: 0o755 }); + + const packManifestPath = resolveIn(outRoot, RUNNER_IMAGE_PATHS.providerPackManifest); + const pack = existsSync(packManifestPath) ? JSON.parse(readFileSync(packManifestPath, "utf8")) : null; + const sha256 = {}; + for (const [name, relative] of Object.entries(RUNNER_IMAGE_PATHS)) { + if (name === "manifest" || DIRECTORY_PATHS.has(name)) continue; + const absolute = resolveIn(outRoot, relative); + if (existsSync(absolute)) sha256[name] = sha256File(absolute); + } + + const manifest = { + schema: RUNNER_IMAGE_SCHEMA, + inputsDigest: { schema: RUNNER_IMAGE_INPUTS_SCHEMA, digest: identity.digest }, + buildInputsDigest: { schema: BUILD_INPUTS_SCHEMA, digest: identity.buildInputs.digest }, + sourceRevision, + // Only a build made to be published may carry the image identity in its + // pack. A Runner built inline by another image build is not that image. + publication, + platform: { os: platform.os, architecture: platform.architecture }, + libc: { family: "glibc", baseline: libc.baseline, buildVersion: libc.buildVersion, runnerdRequires: libc.runnerdRequires }, + providerPack: pack === null ? null : { digest: pack.digest, target: pack.payload?.target ?? null }, + paths: { ...RUNNER_IMAGE_PATHS }, + sha256, + }; + const manifestPath = resolveIn(outRoot, RUNNER_IMAGE_PATHS.manifest); + writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); + chmodSync(manifestPath, 0o644); + return manifest; +} + +/** Every entry under `root` that an unrelated user cannot read, up to `limit`. */ +function unreadableEntries(root, limit = 5) { + const found = []; + const visit = (directory, prefix) => { + for (const entry of readdirSync(directory, { withFileTypes: true })) { + if (found.length >= limit) return; + const relative = prefix ? `${prefix}/${entry.name}` : entry.name; + const absolute = path.join(directory, entry.name); + if (entry.isSymbolicLink()) continue; + const mode = lstatSync(absolute).mode; + if (entry.isDirectory()) { + if ((mode & 0o005) !== 0o005) found.push(relative); + else visit(absolute, relative); + } else if ((mode & 0o004) === 0) { + found.push(relative); + } + } + }; + visit(root, ""); + return found; +} + +function elfMachine(file) { + const header = Buffer.alloc(20); + const descriptor = openSync(file, "r"); + try { + if (readSync(descriptor, header, 0, header.length, 0) < header.length) return null; + } finally { + closeSync(descriptor); + } + if (header.readUInt32BE(0) !== 0x7f454c46) return null; + // EI_DATA 1 is little-endian, which both supported architectures use. + return header[5] === 1 ? header.readUInt16LE(18) : null; +} + +function checkManifestShape(manifest, problems, { allowUnstamped }) { + if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) { + problems.push("runner-image.json is not a JSON object"); + return false; + } + if (manifest.schema !== RUNNER_IMAGE_SCHEMA) problems.push(`runner-image.json schema is ${JSON.stringify(manifest.schema)}, not ${RUNNER_IMAGE_SCHEMA}`); + const stamped = manifest.sourceRevision !== null && manifest.sourceRevision !== undefined; + if (typeof manifest.publication !== "boolean") problems.push("publication must say whether this is a publication build"); + else if (manifest.publication && !stamped) problems.push("a publication build must have a source revision"); + if (stamped) { + if (typeof manifest.sourceRevision !== "string" || !REVISION.test(manifest.sourceRevision)) problems.push("sourceRevision is not a full Git SHA"); + } else if (!allowUnstamped) { + problems.push("the image has no source revision: it was built without PAPERCLIP_RUNNER_SOURCE_REVISION and has no provider pack"); + } + for (const [key, schema] of [["inputsDigest", RUNNER_IMAGE_INPUTS_SCHEMA], ["buildInputsDigest", BUILD_INPUTS_SCHEMA]]) { + const value = manifest[key]; + if (value?.schema !== schema || typeof value?.digest !== "string" || !HEX_64.test(value.digest)) { + problems.push(`${key} must be { schema: ${schema}, digest: <64 hexadecimal characters> }`); + } + } + if (manifest.platform?.os !== "linux" || !ARCHITECTURES[manifest.platform?.architecture]) { + problems.push(`platform must be linux/amd64 or linux/arm64, not ${JSON.stringify(manifest.platform)}`); + } + const libc = manifest.libc; + if (libc?.family !== "glibc" || typeof libc?.baseline !== "string" || !libc.baseline + || !VERSION.test(libc?.buildVersion ?? "") || !VERSION.test(libc?.runnerdRequires ?? "")) { + problems.push("libc must record the glibc family, the baseline release, its version and the version the daemon requires"); + } else if (compareVersions(libc.runnerdRequires, libc.buildVersion) > 0) { + problems.push(`the daemon requires glibc ${libc.runnerdRequires}, newer than the ${libc.buildVersion} baseline it was compiled on`); + } + if (canonicalJson(manifest.paths ?? null) !== canonicalJson(RUNNER_IMAGE_PATHS)) { + problems.push("paths does not match the documented layout (RUNNER_IMAGE_PATHS)"); + } + if (!manifest.sha256 || typeof manifest.sha256 !== "object") problems.push("sha256 must map file paths to their digests"); + return stamped; +} + +/** + * The stamp the Runner's own build wrote. A build that reuses this dist + * (server/scripts/prepare-runner-vendor.mjs) accepts it only when the stamp + * names the same inputs and platform and every recorded output is intact. + */ +function checkBuildStamp(root, manifest, problems) { + const packageRoot = resolveIn(root, RUNNER_IMAGE_PATHS.runnerPackage); + if (buildInputsStampPath(packageRoot) !== resolveIn(root, RUNNER_IMAGE_PATHS.runnerBuildStamp)) { + problems.push("the documented build stamp path is not where the Runner build looks for it"); + return; + } + const stamp = readJson(resolveIn(root, RUNNER_IMAGE_PATHS.runnerBuildStamp), problems, "the Runner build stamp"); + if (!stamp) return; + if (stamp.schema !== BUILD_INPUTS_SCHEMA || !Array.isArray(stamp.outputs)) { + problems.push(`the Runner build stamp schema is ${JSON.stringify(stamp.schema)}, not ${BUILD_INPUTS_SCHEMA}`); + return; + } + if (stamp.digest !== manifest.buildInputsDigest.digest) problems.push("the Runner build stamp names other inputs than runner-image.json"); + const architecture = ARCHITECTURES[manifest.platform.architecture].node; + if (stamp.platform !== "linux" || stamp.arch !== architecture) { + problems.push(`the Runner build stamp was recorded on ${stamp.platform}/${stamp.arch}, not linux/${architecture}`); + } + const missing = expectedBuildOutputs(packageRoot, "linux").filter((file) => !existsSync(file)); + if (missing.length > 0) problems.push(`the Runner build output ${path.relative(packageRoot, missing[0])} is missing`); + if (stamp.outputs.length === 0) problems.push("the Runner build stamp records no outputs"); + const changed = findChangedBuildOutput(packageRoot, stamp.outputs); + if (changed) problems.push(`the Runner build output ${changed.path} is ${changed.state} since the build recorded its stamp`); +} + +function checkProviderPack(root, manifest, problems) { + const packRoot = resolveIn(root, RUNNER_IMAGE_PATHS.providerPack); + const pack = readJson(resolveIn(root, RUNNER_IMAGE_PATHS.providerPackManifest), problems, "provider-pack.json"); + if (!pack) return null; + const payload = pack.payload; + if (pack.schema !== PROVIDER_PACK_SCHEMA || !payload || typeof payload !== "object") { + problems.push("provider-pack.json is not a provider pack manifest"); + return null; + } + const digest = `sha256:${createHash("sha256").update(canonicalJson(payload)).digest("hex")}`; + if (pack.digest !== digest) problems.push("provider-pack.json digest does not match its payload"); + if (manifest.providerPack?.digest !== pack.digest) problems.push("runner-image.json providerPack.digest does not match provider-pack.json"); + if (payload.runnerSourceRevision !== manifest.sourceRevision) { + problems.push(`the provider pack was built from ${payload.runnerSourceRevision}, but the image source revision is ${manifest.sourceRevision}`); + } + if (manifest.publication) { + if (payload.runnerInputsDigest !== manifest.inputsDigest?.digest) { + problems.push("the provider pack runnerInputsDigest does not match the image inputs digest"); + } + } else if (Object.hasOwn(payload, "runnerInputsDigest")) { + problems.push("the provider pack records runnerInputsDigest, but this is not a publication build"); + } + const architecture = ARCHITECTURES[manifest.platform?.architecture]; + if (payload.target?.platform !== "linux" || payload.target?.architecture !== architecture?.node) { + problems.push(`the provider pack targets ${JSON.stringify(payload.target)}, not the image platform`); + } + const artifacts = payload.artifacts && typeof payload.artifacts === "object" ? Object.entries(payload.artifacts) : []; + if (artifacts.length === 0) problems.push("provider-pack.json lists no artifacts"); + for (const [name, artifact] of artifacts) { + if (typeof artifact?.path !== "string" || !SHA256.test(artifact?.sha256 ?? "")) { + problems.push(`provider pack artifact ${name} has no path and digest`); + continue; + } + const located = locate(packRoot, artifact.path); + if (located.state === "outside") { + problems.push(`provider pack artifact ${name} resolves outside the pack: ${artifact.path}`); + } else if (located.state === "missing") { + problems.push(`provider pack artifact ${name} is missing: ${artifact.path}`); + } else if (!lstatSync(located.path).isFile() || sha256File(located.path) !== artifact.sha256) { + problems.push(`provider pack artifact ${name} does not match its digest: ${artifact.path}`); + } + } + // The two kinds of tree digest the manifest records, recomputed with the + // pack builder's own function. + const tree = (label, relative, expected) => { + const located = typeof relative === "string" ? locate(packRoot, relative) : { state: "missing" }; + if (located.state === "outside") { + problems.push(`${label} resolves outside the pack`); + } else if (located.state === "missing" || !lstatSync(located.path).isDirectory() || readdirSync(located.path).length === 0) { + problems.push(`${label} is missing`); + } else if (!SHA256.test(expected ?? "") || sha256Tree(located.path) !== expected) { + problems.push(`${label} does not match its tree digest`); + } + }; + tree("the provider pack dist tree", "dist", payload.distDigest); + for (const group of ["providers", "candidateProviders"]) { + for (const [name, provider] of Object.entries(payload[group] ?? {})) { + tree(`the provider pack asset tree of ${name}`, provider?.path, provider?.sha256); + } + } + const lock = payload.artifacts?.productionLock?.sha256; + if (lock !== manifest.sha256?.lockfile) problems.push("the lockfile at the image root is not the one the provider pack was installed from"); + return pack; +} + +function checkArchives(root, pack, problems) { + const receipt = readJson(resolveIn(root, RUNNER_IMAGE_PATHS.providerPackArchiveReceipt), problems, "provider-pack.archive.json"); + if (!receipt) return; + if (receipt.schema !== PROVIDER_PACK_ARCHIVE_SCHEMA || receipt.encoding !== "tar+zstd") { + problems.push("provider-pack.archive.json is not a layered provider pack archive receipt"); + return; + } + if (receipt.providerPackDigest !== pack.digest) problems.push("the transport archives belong to another provider pack"); + const archives = resolveIn(root, RUNNER_IMAGE_PATHS.providerPackArchives); + const packRoot = resolveIn(root, RUNNER_IMAGE_PATHS.providerPack); + const verify = (name, expected) => { + const located = locate(archives, name); + if (located.state === "outside") problems.push(`transport archive ${name} resolves outside the image`); + else if (located.state === "missing") problems.push(`transport archive ${name} is missing`); + else if (!lstatSync(located.path).isFile() || lstatSync(located.path).size !== expected?.bytes + || sha256File(located.path) !== `sha256:${expected?.sha256}`) { + problems.push(`transport archive ${name} does not match its receipt`); + } + }; + verify("overlay.tar.zst", receipt.overlay); + if (!Array.isArray(receipt.files)) { + problems.push("provider-pack.archive.json lists no files"); + return; + } + for (const [index, file] of receipt.files.entries()) { + verify(`${index}.tar.zst`, file?.archive); + const located = typeof file?.path === "string" ? locate(packRoot, file.path) : { state: "missing" }; + if (located.state === "outside") { + problems.push(`archived file ${file.path} resolves outside the pack`); + } else if (located.state === "missing") { + problems.push(`archived file ${file?.path} is missing from the provider pack`); + } else if (!lstatSync(located.path).isFile() || lstatSync(located.path).size !== file.bytes + || sha256File(located.path) !== `sha256:${file.sha256}`) { + problems.push(`archived file ${file.path} does not match the provider pack`); + } + } +} + +/** + * The permission bits an entry has in the image when the transport archives + * carry it with `mode`. The image build writes the archives first and then + * runs `chmod -R a+rX` on the tree, as the application image does, so the pack + * in the image is the archived pack plus that grant: read for everyone, and + * search or execute for everyone where it is a directory or was executable. + */ +function modeAfterImageGrant(mode, isDirectory) { + const permissions = mode & 0o7777; + return permissions | 0o444 | (isDirectory || (permissions & 0o111) !== 0 ? 0o111 : 0); +} + +/** + * The tar command that extracts a transport archive stream into + * `destination`. A sandbox runs GNU tar with exactly these options + * (server/src/services/native-runtime/provider-pack-layers.ts), except that it + * lets tar start `zstd`; here the stream arrives decompressed on stdin, so the + * build needs no zstd program. bsdtar has no --delay-directory-restore; it is + * accepted so the check also runs on a development machine, and the result + * says which tar ran. + */ +function tarExtraction(destination) { + const version = spawnSync("tar", ["--version"], { encoding: "utf8" }); + const banner = `${version.stdout ?? ""}${version.stderr ?? ""}`; + if (version.status !== 0) return null; + if (banner.includes("GNU tar")) { + return { + tar: "GNU tar", + args: ["--ignore-zeros", "-xf", "-", "--no-same-owner", "--same-permissions", "--delay-directory-restore", "-C", destination], + }; + } + if (banner.includes("bsdtar")) { + return { tar: "bsdtar", args: ["--ignore-zeros", "-xf", "-", "--no-same-owner", "-p", "-C", destination] }; + } + return null; +} + +/** Every entry under `root`, by path relative to it: its kind, permission bits, size and link target. */ +function treeEntries(root) { + /** @type {Map} */ + const entries = new Map(); + const visit = (directory, prefix) => { + for (const entry of readdirSync(directory, { withFileTypes: true })) { + const relative = prefix ? `${prefix}/${entry.name}` : entry.name; + const absolute = path.join(directory, entry.name); + const stat = lstatSync(absolute); + const kind = stat.isSymbolicLink() ? "link" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other"; + entries.set(relative, { kind, mode: stat.mode & 0o7777, size: stat.size, target: kind === "link" ? readlinkSync(absolute) : null }); + if (kind === "directory") visit(absolute, relative); + } + }; + visit(root, ""); + return entries; +} + +/** Up to five examples and the count, so one wrong archive does not print the whole pack. */ +function summarize(problems, label, items) { + if (items.length === 0) return; + const shown = items.slice(0, 5).join(", "); + problems.push(`${label} (${items.length}): ${shown}${items.length > 5 ? ", ..." : ""}`); +} + +/** + * Compares what the transport archives extracted to with the provider pack: + * the same paths, the same kind of entry at each, the same content for files, + * the same target for links, and the same permission bits once the image + * build's grant is applied to the extracted ones (see modeAfterImageGrant). + * All twelve permission bits are compared for files and directories. A link's + * own mode is not: it is not portable and nothing reads it. + */ +function compareExtractedPack(packRoot, extractedRoot, receipt, problems) { + const pack = treeEntries(packRoot); + const extracted = treeEntries(extractedRoot); + const octal = (mode) => mode.toString(8).padStart(4, "0"); + const missing = []; + const kinds = []; + const contents = []; + const targets = []; + const modes = []; + for (const [relative, expected] of pack) { + const actual = extracted.get(relative); + if (!actual) { + missing.push(relative); + } else if (actual.kind !== expected.kind || expected.kind === "other") { + kinds.push(`${relative} (${actual.kind}, the pack has a ${expected.kind})`); + } else if (expected.kind === "link") { + if (actual.target !== expected.target) targets.push(`${relative} (-> ${actual.target}, the pack has -> ${expected.target})`); + } else { + if (expected.kind === "file" && (actual.size !== expected.size + || sha256File(path.join(extractedRoot, ...relative.split("/"))) !== sha256File(path.join(packRoot, ...relative.split("/"))))) { + contents.push(relative); + } + const granted = modeAfterImageGrant(actual.mode, expected.kind === "directory"); + if (granted !== expected.mode) modes.push(`${relative} (archived ${octal(actual.mode)}, the pack has ${octal(expected.mode)})`); + } + } + const extra = [...extracted.keys()].filter((relative) => !pack.has(relative)); + summarize(problems, "the transport archives do not carry these provider pack entries", missing); + summarize(problems, "the transport archives carry entries the provider pack does not have", extra); + summarize(problems, "the transport archives carry another kind of entry", kinds); + summarize(problems, "the transport archives carry other content", contents); + summarize(problems, "the transport archives carry another link target", targets); + summarize(problems, "the transport archives carry other permissions", modes); + // The receipt's mode is what a sandbox sets on a large file it reuses from + // an older pack instead of extracting it. + const receiptModes = []; + for (const file of receipt.files) { + const actual = typeof file?.path === "string" ? extracted.get(file.path) : undefined; + if (actual?.kind === "file" && (actual.mode & 0o777) !== file.mode) { + receiptModes.push(`${file.path} (receipt ${octal(file.mode ?? 0)}, archived ${octal(actual.mode)})`); + } + } + summarize(problems, "the receipt records other permissions than the transport archives carry", receiptModes); +} + +/** + * Extracts the transport archives the way a sandbox does when it holds no + * older pack, and compares the result with the provider pack. Returns every + * problem found, and which tar ran. + * + * A sandbox receives every numbered archive and then the overlay as one + * stream and runs, under `umask 077`, + * tar --zstd --ignore-zeros -xf --no-same-owner --same-permissions + * --delay-directory-restore -C + * (server/src/services/native-runtime/provider-pack-layers.ts). This does the + * same, in a temporary directory that it removes again. tar refuses a member + * that would be written outside the destination, and that refusal fails the + * check. + * @param {string} root + * @returns {Promise<{ problems: string[], tar: string | null }>} + */ +export async function checkProviderPackArchives(root) { + /** @type {string[]} */ + const problems = []; + const packRoot = resolveIn(root, RUNNER_IMAGE_PATHS.providerPack); + const archives = resolveIn(root, RUNNER_IMAGE_PATHS.providerPackArchives); + const receipt = readJson(resolveIn(root, RUNNER_IMAGE_PATHS.providerPackArchiveReceipt), problems, "provider-pack.archive.json"); + if (!receipt) return { problems, tar: null }; + if (receipt.schema !== PROVIDER_PACK_ARCHIVE_SCHEMA || !Array.isArray(receipt.files)) { + return { problems: ["provider-pack.archive.json is not a layered provider pack archive receipt"], tar: null }; + } + // The order a sandbox extracts in: the large files, then the overlay. + const names = [...receipt.files.map((_file, index) => `${index}.tar.zst`), "overlay.tar.zst"]; + let listed = []; + try { + listed = readdirSync(archives); + } catch { + return { problems: [`${RUNNER_IMAGE_PATHS.providerPackArchives} is missing`], tar: null }; + } + summarize(problems, "the receipt lists transport archives that are missing", names.filter((name) => !listed.includes(name))); + summarize(problems, "provider-pack.archives holds files the receipt does not list", listed.filter((name) => !names.includes(name))); + for (const name of names) { + const located = locate(archives, name); + if (located.state === "inside" && !lstatSync(located.path).isFile()) problems.push(`transport archive ${name} is not a regular file`); + if (located.state === "outside") problems.push(`transport archive ${name} resolves outside the image`); + } + if (problems.length > 0) return { problems, tar: null }; + + const destination = mkdtempSync(path.join(tmpdir(), "paperclip-runner-image-archives-")); + try { + const extraction = tarExtraction(destination); + if (!extraction) { + return { problems: ["the transport archives cannot be extracted here: `tar` is neither GNU tar nor bsdtar"], tar: null }; + } + const child = spawn("sh", ["-c", 'umask 077; exec tar "$@"', "sh", ...extraction.args], { stdio: ["pipe", "ignore", "pipe"] }); + let stderr = ""; + child.stderr.on("data", (chunk) => { + if (stderr.length < 4000) stderr += chunk; + }); + // tar can exit before it has read everything; the exit status reports why. + child.stdin.on("error", () => {}); + const exited = new Promise((resolve) => { + child.on("error", () => resolve(null)); + child.on("close", (code) => resolve(code)); + }); + let tarGone = false; + void exited.then(() => { + tarGone = true; + }); + /** @type {{ name: string, message: string } | null} */ + let undecodable = null; + for (const name of names) { + if (tarGone) break; + // One decompressor for each archive: each is a zstd stream of its own, + // and tar reads their tar streams one after the other. + const decompress = createZstdDecompress(); + const decoded = pipeline(createReadStream(path.join(archives, name)), decompress); + decoded.catch(() => {}); + try { + for await (const chunk of decompress) { + if (tarGone) break; + if (!child.stdin.write(chunk)) await Promise.race([once(child.stdin, "drain"), exited]); + } + if (!tarGone) await decoded; + } catch (error) { + // Once tar is gone its exit status is the finding, not the stream + // that was cut off behind it. + if (!tarGone) undecodable = { name, message: error instanceof Error ? error.message : String(error) }; + break; + } + } + if (undecodable) child.kill(); + child.stdin.end(); + const status = await exited; + if (undecodable) { + problems.push(`transport archive ${undecodable.name} is not a zstd archive (${undecodable.message})`); + } else if (status !== 0) { + problems.push(`${extraction.tar} could not extract the transport archives (exit ${status}): ${stderr.trim().slice(-1500) || "no message"}`); + } else { + compareExtractedPack(packRoot, destination, receipt, problems); + } + return { problems, tar: extraction.tar }; + } finally { + // An archive can carry a directory its owner cannot write to. + spawnSync("chmod", ["-R", "u+rwX", destination]); + rmSync(destination, { recursive: true, force: true }); + } +} + +/** + * Verifies the tree at `root` against the layout contract. Returns every + * problem found; an empty list means the tree is a valid Runner image. + * It reads the transport archives' bytes but does not extract them: + * checkProviderPackArchives does, and the `check` command runs both. + * @param {string} root + * @param {{ + * allowUnstamped?: boolean, + * expectInputsDigest?: string | null, + * expectSourceRevision?: string | null, + * expectArchitecture?: string | null, + * }} [options] + * @returns {string[]} + */ +export function checkRunnerImageLayout(root, { + allowUnstamped = false, + expectInputsDigest = null, + expectSourceRevision = null, + expectArchitecture = null, +} = {}) { + const problems = []; + const manifestPath = resolveIn(root, RUNNER_IMAGE_PATHS.manifest); + if (!existsSync(manifestPath)) return ["runner-image.json is missing"]; + const manifest = readJson(manifestPath, problems, "runner-image.json"); + if (manifest === null) return problems; + const stamped = checkManifestShape(manifest, problems, { allowUnstamped }); + if (problems.length > 0) return problems; + + if (expectInputsDigest !== null && manifest.publication !== true) { + problems.push("an inputs digest is expected, but this is not a publication build"); + } + if (expectInputsDigest !== null && manifest.inputsDigest?.digest !== expectInputsDigest) { + problems.push(`inputs digest is ${manifest.inputsDigest?.digest ?? "absent"}, expected ${expectInputsDigest}`); + } + if (expectSourceRevision !== null && manifest.sourceRevision !== expectSourceRevision) { + problems.push(`source revision is ${manifest.sourceRevision ?? "absent"}, expected ${expectSourceRevision}`); + } + if (expectArchitecture !== null && manifest.platform.architecture !== expectArchitecture) { + problems.push(`architecture is ${manifest.platform.architecture}, expected ${expectArchitecture}`); + } + + for (const [name, relative] of Object.entries(RUNNER_IMAGE_PATHS)) { + if (name === "manifest" || (!stamped && STAMPED_ONLY_PATHS.has(name))) continue; + const absolute = resolveIn(root, relative); + let stat; + try { + stat = lstatSync(absolute); + } catch { + problems.push(`documented path ${relative} (${name}) is missing`); + continue; + } + if (locate(root, relative).state !== "inside") { + problems.push(`documented path ${relative} (${name}) resolves outside the image`); + continue; + } + if (DIRECTORY_PATHS.has(name)) { + if (!stat.isDirectory()) problems.push(`${relative} (${name}) must be a directory`); + continue; + } + if (!stat.isFile() || stat.size === 0) { + problems.push(`${relative} (${name}) must be a non-empty regular file`); + continue; + } + if (!SHA256.test(manifest.sha256[name] ?? "")) problems.push(`runner-image.json records no digest for ${relative} (${name})`); + else if (sha256File(absolute) !== manifest.sha256[name]) problems.push(`${relative} (${name}) does not match the digest in runner-image.json`); + } + + for (const name of ["runnerd", "runnerDistRunnerd"]) { + const runnerd = resolveIn(root, RUNNER_IMAGE_PATHS[name]); + if (!existsSync(runnerd)) continue; + if ((lstatSync(runnerd).mode & 0o111) !== 0o111) problems.push(`${RUNNER_IMAGE_PATHS[name]} is not executable by every user`); + if (elfMachine(runnerd) !== ARCHITECTURES[manifest.platform.architecture].elfMachine) { + problems.push(`${RUNNER_IMAGE_PATHS[name]} is not a linux/${manifest.platform.architecture} executable`); + } + } + if (manifest.sha256.runnerd !== manifest.sha256.runnerDistRunnerd) { + problems.push("the daemon at the image root is not the one in the Runner build output"); + } + if (existsSync(resolveIn(root, RUNNER_IMAGE_PATHS.runnerBuildStamp))) checkBuildStamp(root, manifest, problems); + + const unreadable = unreadableEntries(root); + if (unreadable.length > 0) problems.push(`not readable by every user: ${unreadable.join(", ")}`); + + if (stamped) { + const pack = checkProviderPack(root, manifest, problems); + if (pack) checkArchives(root, pack, problems); + } else if (manifest.providerPack !== null) { + problems.push("an image without a source revision must not record a provider pack"); + } + return problems; +} + +const COMMAND_FLAGS = Object.freeze({ + write: { out: "value", workspace: "value", identity: "value", "source-revision": "value", publication: "boolean" }, + check: { + "allow-unstamped": "boolean", + "expect-inputs-digest": "value", + "expect-source-revision": "value", + "expect-architecture": "value", + }, +}); + +/** + * Splits a command line into positional arguments and the flags the command + * knows. Throws on an unknown or repeated flag and on a missing or empty value. + * @param {"write" | "check"} command + * @param {string[]} argv + */ +export function parseLayoutArguments(command, argv) { + const known = COMMAND_FLAGS[command]; + /** @type {string[]} */ + const positional = []; + /** @type {Record} */ + const flags = {}; + for (let index = 0; index < argv.length; index += 1) { + const argument = argv[index]; + if (!argument.startsWith("--")) { + positional.push(argument); + continue; + } + const name = argument.slice(2); + if (!Object.hasOwn(known, name)) throw new Error(`${command} does not take ${argument}`); + if (Object.hasOwn(flags, name)) throw new Error(`${argument} is given twice`); + if (known[name] === "boolean") { + flags[name] = true; + continue; + } + const value = argv[index += 1]; + if (value === undefined || value === "" || value.startsWith("--")) throw new Error(`${argument} needs a value`); + flags[name] = value; + } + return { positional, flags }; +} + +function expectation(flags, name, pattern, description) { + const value = flags[name]; + if (value === undefined) return null; + if (typeof value !== "string" || !pattern.test(value)) throw new Error(`--${name} must be ${description}`); + return value; +} + +const invoked = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null; +if (invoked === import.meta.url) { + try { + const [command, ...rest] = process.argv.slice(2); + if (command !== "write" && command !== "check") { + throw new Error("Usage: runner-image-layout.mjs write ... | check DIR [...]"); + } + const { positional, flags } = parseLayoutArguments(command, rest); + if (command === "write") { + if (positional.length > 0) throw new Error(`write takes no positional argument: ${positional[0]}`); + for (const name of ["out", "workspace", "identity"]) { + if (!flags[name]) throw new Error(`write needs --${name}`); + } + const workspaceRoot = path.resolve(String(flags.workspace)); + const manifest = writeRunnerImageManifest({ + outRoot: path.resolve(String(flags.out)), + workspaceRoot, + identity: JSON.parse(readFileSync(path.resolve(String(flags.identity)), "utf8")), + ...detectBuildEnvironment(resolveIn(workspaceRoot, WORKSPACE_SOURCES.runnerd)), + sourceRevision: expectation(flags, "source-revision", REVISION, "a full Git SHA"), + publication: flags.publication === true, + }); + process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`); + } else { + if (positional.length !== 1) throw new Error("check takes exactly one directory"); + const root = path.resolve(positional[0]); + const problems = checkRunnerImageLayout(root, { + allowUnstamped: flags["allow-unstamped"] === true, + expectInputsDigest: expectation(flags, "expect-inputs-digest", HEX_64, "64 hexadecimal characters"), + expectSourceRevision: expectation(flags, "expect-source-revision", REVISION, "a full Git SHA"), + expectArchitecture: expectation(flags, "expect-architecture", /^(?:amd64|arm64)$/, "amd64 or arm64"), + }); + // Only a tree without a source revision has no archives; the layout + // check above has already refused that tree unless it was allowed. + let archives = "The tree has no provider pack, so there are no transport archives to extract."; + if (existsSync(resolveIn(root, RUNNER_IMAGE_PATHS.providerPackArchiveReceipt))) { + const roundTrip = await checkProviderPackArchives(root); + problems.push(...roundTrip.problems); + archives = roundTrip.tar === "GNU tar" + ? "The transport archives were extracted with GNU tar, as a sandbox extracts them, and match the provider pack." + : `The transport archives were extracted with ${roundTrip.tar} and match the provider pack. A sandbox uses GNU tar; run this on Linux for that check.`; + } + if (problems.length > 0) { + process.stderr.write(`Runner image layout check failed:\n${problems.map((problem) => `- ${problem}`).join("\n")}\n`); + process.exit(1); + } + process.stdout.write(`Runner image layout check passed. ${archives}\n`); + } + } catch (error) { + process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); + process.exit(1); + } +} diff --git a/server/src/__tests__/runner-image-identity.test.ts b/server/src/__tests__/runner-image-identity.test.ts new file mode 100644 index 00000000000..2081c3963ef --- /dev/null +++ b/server/src/__tests__/runner-image-identity.test.ts @@ -0,0 +1,284 @@ +import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { afterEach, describe, expect, it } from "vitest"; +import { computeBuildInputsDigest } from "../../../packages/paperclip-runner/scripts/build-inputs.mjs"; +import { + RUNNER_IMAGE_CONTEXT_INPUTS, + RUNNER_IMAGE_INPUTS_SCHEMA, + computeContextTreeDigest, + computeRunnerImageIdentity, +} from "../../../scripts/runner-image-identity.mjs"; + +/** + * The Runner image is named after its identity. An identity that misses an + * input gives a changed Runner the name of an older one. + */ + +const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", ".."); +const dockerfile = readFileSync(path.join(repoRoot, "Dockerfile"), "utf8"); + +const roots: string[] = []; +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); +}); + +function write(root: string, relative: string, content: string) { + const file = path.join(root, ...relative.split("/")); + mkdirSync(path.dirname(file), { recursive: true }); + writeFileSync(file, content); + return file; +} + +/** A repository with the real Dockerfile and one small file for every kind of input. */ +function repository(): string { + const root = mkdtempSync(path.join(tmpdir(), "runner-image-identity-")); + roots.push(root); + write(root, "Dockerfile", dockerfile); + write(root, ".dockerignore", "node_modules\n"); + for (const input of RUNNER_IMAGE_CONTEXT_INPUTS) { + if (!input.startsWith("packages/paperclip-") && input !== "patches") write(root, input, `input ${input}\n`); + } + write(root, "packages/paperclip-runner/package.json", "{}\n"); + write(root, "packages/paperclip-runner/src/index.ts", "export const runner = 1;\n"); + write(root, "packages/paperclip-runner/runner/crates/runner-core/src/lib.rs", "pub fn runner() {}\n"); + write(root, "packages/paperclip-eval-kernel/src/index.ts", "export const kernel = 1;\n"); + write(root, "patches/acpx@0.22.0.patch", "patch\n"); + write(root, "ui/src/App.tsx", "export const app = 1;\n"); + write(root, "server/src/index.ts", "export const server = 1;\n"); + write(root, "packages/shared/src/index.ts", "export const shared = 1;\n"); + return root; +} + +const digestOf = (root: string) => computeRunnerImageIdentity(root).digest as string; + +describe("Runner image identity", () => { + it("reports the tag, the context tree, the Dockerfile and the Runner build inputs", () => { + const identity = computeRunnerImageIdentity(repository()); + expect(identity.schema).toBe(RUNNER_IMAGE_INPUTS_SCHEMA); + expect(identity.digest).toMatch(/^[0-9a-f]{64}$/); + expect(identity.tag).toBe(`inputs-${identity.digest}`); + expect(identity.image).toBe("ghcr.io/paperclipai/paperclip-runner"); + expect(identity.platforms).toEqual(["linux/amd64", "linux/arm64"]); + expect(identity.context.inputs).toEqual(RUNNER_IMAGE_CONTEXT_INPUTS); + expect(identity.context.digest).toMatch(/^[0-9a-f]{64}$/); + expect(identity.dockerfile.sha256).toMatch(/^[0-9a-f]{64}$/); + expect(identity.buildInputs.schema).toBe("paperclip.runner-build-inputs.v2"); + }); + + it("is the same for the same tree", () => { + const root = repository(); + expect(digestOf(root)).toBe(digestOf(root)); + expect(digestOf(repository())).toBe(digestOf(root)); + }); + + it.each([ + ["a Runner TypeScript source file", "packages/paperclip-runner/src/index.ts"], + ["a Runner Rust source file", "packages/paperclip-runner/runner/crates/runner-core/src/lib.rs"], + ["the eval kernel the Runner builds first", "packages/paperclip-eval-kernel/src/index.ts"], + ["a dependency patch", "patches/acpx@0.22.0.patch"], + ["the lockfile", "pnpm-lock.yaml"], + ["the root manifest", "package.json"], + ["the pnpm configuration", ".npmrc"], + ["the pack archive script", "scripts/create-provider-pack-archive.mjs"], + ["the layout script", "scripts/runner-image-layout.mjs"], + ["the contract copy that build:typescript checks", "packages/shared/src/provider-failure.generated.ts"], + ["the Dockerfile, in a stage the Runner is not built from", "Dockerfile"], + ])("changes when %s changes", (_label, file) => { + const root = repository(); + const before = digestOf(root); + write(root, file, file === "Dockerfile" ? dockerfile.replace("FROM base AS production\n", "FROM base AS production\nRUN true\n") : "changed\n"); + expect(digestOf(root)).not.toBe(before); + }); + + it.each([ + ["a UI source file", "ui/src/App.tsx"], + ["a server source file", "server/src/index.ts"], + ["another package's source file", "packages/shared/src/index.ts"], + ["a new file outside the Runner's inputs", "server/src/services/new-service.ts"], + ])("does not change when %s changes", (_label, file) => { + const root = repository(); + const before = digestOf(root); + write(root, file, "changed\n"); + expect(digestOf(root)).toBe(before); + }); + + it("refuses an input that is missing from the build context", () => { + const root = repository(); + rmSync(path.join(root, "scripts/create-provider-pack-archive.mjs")); + expect(() => computeRunnerImageIdentity(root)).toThrow(/scripts\/create-provider-pack-archive\.mjs, which is missing/); + }); + + describe("context tree", () => { + // The Runner's build-input digest skips dot-directories and any directory + // named dist, and it does not read file modes. The image build copies + // those paths and modes all the same, so the identity must see them. + it.each([ + ["a file in a dot-directory", "packages/paperclip-runner/runner/.cargo/config.toml"], + ["a file in a directory named dist", "packages/paperclip-runner/src/vendor/dist/bundle.js"], + ])("changes for %s, which the Runner build-input digest does not read", (_label, file) => { + const root = repository(); + const before = computeRunnerImageIdentity(root); + write(root, file, "[build]\n"); + const after = computeRunnerImageIdentity(root); + expect(after.buildInputs.digest).toBe(before.buildInputs.digest); + expect(after.digest).not.toBe(before.digest); + }); + + it("changes when only the executable bit of a file changes", () => { + const root = repository(); + const file = write(root, "packages/paperclip-runner/scripts/provision.sh", "#!/bin/sh\n"); + chmodSync(file, 0o644); + const before = computeRunnerImageIdentity(root); + chmodSync(file, 0o755); + expect(computeBuildInputsDigest(root).digest).toBe(before.buildInputs.digest); + expect(digestOf(root)).not.toBe(before.digest); + }); + + it("records a symbolic link by its target and does not follow it", () => { + const root = repository(); + const link = path.join(root, "packages/paperclip-runner/current"); + symlinkSync("src", link); + const before = digestOf(root); + rmSync(link); + symlinkSync("../../server/src", link); + const after = digestOf(root); + expect(after).not.toBe(before); + write(root, "server/src/index.ts", "changed\n"); + expect(digestOf(root)).toBe(after); + }); + + it("changes when a file is added or removed, and not with the order of a directory listing", () => { + const root = repository(); + const before = digestOf(root); + write(root, "packages/paperclip-eval-kernel/src/extra.ts", "export {};\n"); + expect(digestOf(root)).not.toBe(before); + rmSync(path.join(root, "packages/paperclip-eval-kernel/src/extra.ts")); + expect(digestOf(root)).toBe(before); + const other = repository(); + for (const name of ["b.ts", "Z.ts", "a.ts", "_c.ts"]) write(root, `packages/paperclip-runner/src/${name}`, "x\n"); + for (const name of ["_c.ts", "a.ts", "Z.ts", "b.ts"]) write(other, `packages/paperclip-runner/src/${name}`, "x\n"); + expect(computeContextTreeDigest(root)).toEqual(computeContextTreeDigest(other)); + }); + }); + + describe(".dockerignore", () => { + // Its rules decide which files the build receives, and nothing else. The + // identity is computed inside the build, from the files it received. + it("does not change the identity when its text changes and the received files do not", () => { + const root = repository(); + const before = digestOf(root); + write(root, ".dockerignore", "node_modules\nui/dist\nserver/tmp\n"); + expect(digestOf(root)).toBe(before); + }); + + it("changes the identity when a rule removes a file from the Runner's context", () => { + const root = repository(); + write(root, "packages/paperclip-runner/styles.css", "body {}\n"); + const before = digestOf(root); + // What a new `packages/paperclip-runner/styles.css` rule does to the build context. + rmSync(path.join(root, "packages/paperclip-runner/styles.css")); + expect(digestOf(root)).not.toBe(before); + }); + }); +}); + +/** + * The identity hashes the whole Dockerfile and the context inputs. That is + * the whole of what the build reads only while these three rules hold. + */ +describe("Runner image stages", () => { + const stages = [...dockerfile.matchAll(/^FROM (\S+)(?: AS (\S+))?$/gm)].map((match, index, all) => ({ + from: match[1], + name: match[2] ?? "", + lines: dockerfile.slice(match.index, all[index + 1]?.index ?? dockerfile.length).split("\n").filter((line) => !/^\s*#/.test(line)), + })); + const names = stages.map((stage) => stage.name); + const runner = stages.filter((stage) => stage.name.startsWith("runner-artifacts")); + const copies = (stage: (typeof stages)[number]) => stage.lines.filter((line) => /^COPY\s/.test(line)); + + it("start only from each other, from scratch, or from an image pinned by digest", () => { + expect(runner.length).toBeGreaterThan(3); + for (const stage of runner) { + if (stage.from === "scratch" || names.includes(stage.from)) { + expect(stage.from === "scratch" || stage.from.startsWith("runner-artifacts"), stage.name).toBe(true); + } else { + expect(stage.from, stage.name).toMatch(/@sha256:[0-9a-f]{64}$/); + } + for (const line of copies(stage)) { + const source = /--from=(\S+)/.exec(line)?.[1]; + if (source) expect(source, line).toMatch(/^runner-artifacts/); + } + } + }); + + it("read the build context only through runner-artifacts-context", () => { + for (const stage of runner) { + const text = stage.lines.join("\n"); + expect(text, stage.name).not.toMatch(/^ADD\s/m); + expect(text, stage.name).not.toMatch(/--mount=/); + expect(text, stage.name).not.toMatch(/< !line.includes("--from=")); + // The identity stage copies the Dockerfile itself, whose text the identity covers. + expect(fromContext, stage.name).toEqual(stage.name === "runner-artifacts-identity-compute" ? ["COPY Dockerfile ./"] : []); + } + }); + + it("copy into runner-artifacts-context exactly the paths the identity hashes", () => { + const context = runner.find((stage) => stage.name === "runner-artifacts-context")!; + const sources = copies(context).flatMap((line) => line.split(/\s+/).slice(1, -1)); + expect(sources.filter((source) => source.startsWith("--"))).toEqual([]); + expect([...sources].sort()).toEqual([...RUNNER_IMAGE_CONTEXT_INPUTS].sort()); + }); + + it("end in a file tree, and leave the default target and the application stages alone", () => { + const target = runner.find((stage) => stage.name === "runner-artifacts")!; + expect(target.from).toBe("scratch"); + expect(copies(target)).toEqual(["COPY --from=runner-artifacts-build /out/ /"]); + // `docker build .` builds the last stage. + expect(names.at(-1)).toBe("cloud"); + for (const stage of stages) { + if (!stage.name.startsWith("runner-artifacts")) expect(stage.lines.join("\n"), stage.name).not.toMatch(/runner-artifacts/); + } + }); + + it("name the published image in the pack only for a publication build, which is off by default", () => { + const build = runner.find((stage) => stage.name === "runner-artifacts-build")!.lines.join("\n"); + expect(build).toContain('ARG PAPERCLIP_RUNNER_IMAGE_PUBLICATION=""\n'); + expect(build).toContain('publication="${PAPERCLIP_RUNNER_IMAGE_PUBLICATION}";'); + // The pack builder reads the variable from the environment. It is set in + // one place, inside the branch that tests for a publication build. + expect(build.match(/PAPERCLIP_RUNNER_INPUTS_DIGEST=/g)).toHaveLength(1); + expect(build).toMatch(/if \[ -n "\$publication" \]; then \\\n\s+PAPERCLIP_RUNNER_INPUTS_DIGEST="\$\(node -p /); + expect(build).not.toMatch(/^ENV .*PAPERCLIP_RUNNER_INPUTS_DIGEST/m); + }); + + it("run every output step of the Runner's own build, and know every other step", () => { + // The image build runs the steps of the Runner's `build` script that write + // output, between the two that record the build stamp. This list is the + // whole script: a new step fails here until someone decides whether the + // image build must run it too. + const manifest = JSON.parse(readFileSync(path.join(repoRoot, "packages/paperclip-runner/package.json"), "utf8")); + expect((manifest.scripts.build as string).split(" && ")).toEqual([ + "node scripts/record-build-inputs.mjs --begin", + "pnpm run check:protocol-manifest", + "pnpm run build:typescript", + "pnpm run check:capability-contract", + "pnpm run check:capability-inventory", + "pnpm run check:protocol-coverage", + "node scripts/generate-semantic-contracts.mjs --check", + "node scripts/check-runner-workflow-traceability.mjs", + "pnpm run build:binary", + "node scripts/generate-replay-goldens.mjs --check", + "node scripts/generate-semantic-action-catalog.mjs --check", + "node scripts/record-build-inputs.mjs --finish", + ]); + const build = runner.find((stage) => stage.name === "runner-artifacts-build")!.lines.join("\n"); + for (const step of ["node scripts/record-build-inputs.mjs --begin;", "pnpm run build:typescript;", "pnpm run build:binary;", + "node scripts/record-build-inputs.mjs --finish;", "pnpm install --frozen-lockfile --filter '@paperclipai/paperclip-runner...'"]) { + expect(build).toContain(step); + } + }); +}); diff --git a/server/src/__tests__/runner-image-layout.test.ts b/server/src/__tests__/runner-image-layout.test.ts new file mode 100644 index 00000000000..3c2118400bf --- /dev/null +++ b/server/src/__tests__/runner-image-layout.test.ts @@ -0,0 +1,703 @@ +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { + appendFileSync, + chmodSync, + cpSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + renameSync, + rmSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { zstdCompressSync } from "node:zlib"; +import { afterAll, beforeEach, describe, expect, it } from "vitest"; +import { + BUILD_INPUTS_SCHEMA, + buildInputsStampPath, + collectBuildOutputFiles, +} from "../../../packages/paperclip-runner/scripts/build-inputs.mjs"; +import { sha256Tree } from "../../../packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs"; +import { createProviderPackLayers } from "../../../scripts/create-provider-pack-archive.mjs"; +import { + PROVIDER_PACK_ARCHIVE_SCHEMA, + PROVIDER_PACK_SCHEMA, + RUNNER_IMAGE_INPUTS_SCHEMA, + RUNNER_IMAGE_PATHS, + RUNNER_IMAGE_SCHEMA, + canonicalJson, + checkProviderPackArchives, + checkRunnerImageLayout, + parseLayoutArguments, + writeRunnerImageManifest, +} from "../../../scripts/runner-image-layout.mjs"; + +/** + * The layout contract of the Runner image. Consumers copy the documented + * paths out of the image and trust runner-image.json, so a tree that + * lacks a path, or whose manifest does not describe it, must never pass. + */ + +const REVISION = "a".repeat(40); +const INPUTS = "1".repeat(64); +const BUILD_INPUTS = "2".repeat(64); +const identity = { schema: RUNNER_IMAGE_INPUTS_SCHEMA, digest: INPUTS, buildInputs: { schema: BUILD_INPUTS_SCHEMA, digest: BUILD_INPUTS } }; +const platform = { os: "linux", architecture: "amd64" }; +const libc = { baseline: "debian-bookworm", buildVersion: "2.36", runnerdRequires: "2.34" }; +const sha256 = (bytes: Buffer | string) => createHash("sha256").update(bytes).digest("hex"); + +const layoutScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "scripts", "runner-image-layout.mjs"); +const scratch = mkdtempSync(path.join(tmpdir(), "runner-image-layout-")); +afterAll(() => rmSync(scratch, { recursive: true, force: true })); +let sequence = 0; + +function write(root: string, relative: string, content: Buffer | string) { + const file = path.join(root, ...relative.split("/")); + mkdirSync(path.dirname(file), { recursive: true }); + writeFileSync(file, content); + return file; +} + +/** The first bytes of a little-endian ELF executable for the given machine. */ +function elf(machine: number) { + const header = Buffer.alloc(64); + header.writeUInt32BE(0x7f454c46, 0); + header[4] = 2; + header[5] = 1; + header.writeUInt16LE(machine, 18); + return header; +} + +/** A Runner package as its build leaves it: build output and the stamp that describes it. */ +function workspace(root: string, { machine = 62, arch = "x64", digest = BUILD_INPUTS } = {}) { + const runner = "packages/paperclip-runner"; + write(root, "pnpm-lock.yaml", "lockfileVersion: '9.0'\n"); + write(root, `${runner}/package.json`, '{"name":"@paperclipai/paperclip-runner","type":"module"}\n'); + write(root, `${runner}/scripts/provision-grok.mjs`, "// provisions Grok\n"); + write(root, `${runner}/src/providers/grok/platforms.json`, '{"version":"1.0.13"}\n'); + write(root, `${runner}/src/live/runnerd-codex-transport.ts`, 'const RUNNER_CLIENT_VERSION = "0.3.0";\n'); + for (const file of ["index.js", "live/index.js", "testing.js"]) write(root, `${runner}/dist/${file}`, `// ${file}\n`); + chmodSync(write(root, `${runner}/dist/bin/paperclip-runnerd`, elf(machine)), 0o755); + const packageRoot = path.join(root, ...runner.split("/")); + const outputs = collectBuildOutputFiles(packageRoot); + write(packageRoot, path.relative(packageRoot, buildInputsStampPath(packageRoot)).split(path.sep).join("/"), JSON.stringify({ + schema: BUILD_INPUTS_SCHEMA, digest, platform: "linux", arch, outputCount: outputs.length, outputs, + })); +} + +// The archive writer puts each file of 1 MiB or more in an archive of its own. +const LARGE = Buffer.alloc(1024 * 1024 + 16, "n"); + +/** + * The files the image build produces before it writes runner-image.json: a + * provider pack, and its transport archives written by the script the image + * build runs. The build grants a+rX after it writes the archives, so the pack + * manifest is 0600 inside the archives and 0644 in the image. + */ +async function providerPack(out: string, { revision = REVISION, inputsDigest = INPUTS as string | null, arch = "x64", lock = "lockfileVersion: '9.0'\n" } = {}) { + const pack = path.join(out, "provider-pack"); + const files: Record = { + nodeCommand: ["node_modules/node/bin/node", LARGE], + productionLock: ["pnpm-lock.yaml", lock], + opencodeProxy: ["dist/cli/opencode-app-server-proxy.cjs", "opencodeProxy\n"], + }; + const artifacts: Record = {}; + for (const [name, [relative, content]] of Object.entries(files)) { + write(pack, relative, content); + artifacts[name] = { path: relative, sha256: `sha256:${sha256(content)}` }; + } + chmodSync(path.join(pack, "node_modules/node/bin/node"), 0o755); + mkdirSync(path.join(pack, "node_modules/.bin"), { recursive: true }); + symlinkSync("../node/bin/node", path.join(pack, "node_modules/.bin/node")); + write(pack, "dist/index.js", "// pack dist\n"); + write(pack, "provider-assets/pi/linux-x64/pi.js", "// pi\n"); + const payload = { + target: { platform: "linux", architecture: arch }, + runnerSourceRevision: revision, + ...(inputsDigest === null ? {} : { runnerInputsDigest: inputsDigest }), + distDigest: sha256Tree(path.join(pack, "dist")), + providers: { pi: { path: "provider-assets/pi/linux-x64", sha256: sha256Tree(path.join(pack, "provider-assets/pi/linux-x64")) } }, + artifacts, + }; + const manifest = { schema: PROVIDER_PACK_SCHEMA, digest: `sha256:${sha256(canonicalJson(payload))}`, payload }; + chmodSync(write(pack, "provider-pack.json", `${JSON.stringify(manifest, null, 2)}\n`), 0o600); + const receipt = await createProviderPackLayers(pack); + expect(receipt.files.map((file: { path: string }) => file.path)).toEqual(["node_modules/node/bin/node"]); + chmodSync(path.join(pack, "provider-pack.json"), 0o644); + write(out, "bundles/runnerd-codex-transport.mjs", "export function createCapabilityRunnerdCodexTransport() {}\n"); +} + +/** One built tree for each distinct set of options; every test gets its own copy. */ +const templates = new Map>(); +async function image(options: { stamped?: boolean; publication?: boolean; pack?: object; source?: object } = {}) { + const key = JSON.stringify(options); + if (!templates.has(key)) { + templates.set(key, (async () => { + const { stamped = true, publication = stamped, pack = {}, source = {} } = options; + const root = path.join(scratch, `template-${templates.size}`); + const out = path.join(root, "out"); + workspace(path.join(root, "workspace"), source); + // Only a publication build's pack names the published image. + if (stamped) await providerPack(out, { ...(publication ? {} : { inputsDigest: null }), ...pack }); + writeRunnerImageManifest({ + outRoot: out, workspaceRoot: path.join(root, "workspace"), identity, platform, libc, sourceRevision: stamped ? REVISION : null, publication, + }); + return out; + })()); + } + const copy = path.join(scratch, String(sequence += 1), "out"); + cpSync(await templates.get(key)!, copy, { recursive: true, verbatimSymlinks: true }); + return copy; +} + +const manifestOf = (out: string) => JSON.parse(readFileSync(path.join(out, "runner-image.json"), "utf8")); +function rewriteManifest(out: string, change: (manifest: Record) => void) { + const manifest = manifestOf(out); + change(manifest); + writeFileSync(path.join(out, "runner-image.json"), JSON.stringify(manifest)); +} + +describe("Runner image layout contract", () => { + let out: string; + beforeEach(async () => { + out = await image(); + }); + + it("accepts the tree the image build writes", () => { + expect(checkRunnerImageLayout(out)).toEqual([]); + expect(checkRunnerImageLayout(out, { expectInputsDigest: INPUTS, expectSourceRevision: REVISION, expectArchitecture: "amd64" })).toEqual([]); + const manifest = manifestOf(out); + expect(manifest).toMatchObject({ + schema: RUNNER_IMAGE_SCHEMA, + inputsDigest: { schema: "paperclip.runner-image-inputs.v1", digest: INPUTS }, + buildInputsDigest: { schema: "paperclip.runner-build-inputs.v2", digest: BUILD_INPUTS }, + sourceRevision: REVISION, + publication: true, + platform: { os: "linux", architecture: "amd64" }, + libc: { family: "glibc", baseline: "debian-bookworm", buildVersion: "2.36", runnerdRequires: "2.34" }, + paths: RUNNER_IMAGE_PATHS, + }); + // One daemon, at the root for sandbox images and inside the build output + // for a build that vendors the Runner. + expect(manifest.sha256.runnerd).toBe(manifest.sha256.runnerDistRunnerd); + }); + + it.each(Object.entries(RUNNER_IMAGE_PATHS))("fails when the documented path %s is missing", (name, relative) => { + rmSync(path.join(out, ...(relative as string).split("/")), { recursive: true, force: true }); + const problems = checkRunnerImageLayout(out); + expect(problems.length).toBeGreaterThan(0); + expect(problems.join("\n")).toContain(name === "manifest" ? "runner-image.json is missing" : (relative as string)); + }); + + it.each([ + ["is not JSON", (file: string) => writeFileSync(file, "{")], + ["is not an object", (file: string) => writeFileSync(file, "[]")], + ])("fails when runner-image.json %s", (_label, corrupt) => { + corrupt(path.join(out, "runner-image.json")); + expect(checkRunnerImageLayout(out)).toHaveLength(1); + }); + + it.each<[string, (manifest: Record) => void, RegExp]>([ + ["another schema", (m) => { m.schema = "paperclip.runner-image.v0"; }, /schema/], + ["no inputs digest", (m) => { delete m.inputsDigest; }, /inputsDigest must be/], + ["a short inputs digest", (m) => { m.inputsDigest.digest = "abc"; }, /inputsDigest must be/], + ["another build-inputs schema", (m) => { m.buildInputsDigest.schema = "paperclip.runner-build-inputs.v1"; }, /buildInputsDigest must be/], + ["an abbreviated source revision", (m) => { m.sourceRevision = "abc1234"; }, /sourceRevision/], + ["no word on whether it is a publication build", (m) => { delete m.publication; }, /publication must say/], + ["a publication build without a source revision", (m) => { m.sourceRevision = null; }, /publication build must have a source revision/], + ["an unsupported platform", (m) => { m.platform = { os: "linux", architecture: "riscv64" }; }, /platform must be/], + ["no libc baseline", (m) => { delete m.libc.baseline; }, /libc must record/], + ["a daemon newer than its baseline", (m) => { m.libc.runnerdRequires = "2.38"; }, /requires glibc 2\.38/], + ["an undocumented path", (m) => { m.paths.extra = "extra"; }, /paths does not match/], + ["a moved path", (m) => { m.paths.runnerd = "bin/paperclip-runnerd"; }, /paths does not match/], + ["no digests", (m) => { delete m.sha256; }, /sha256 must map/], + ])("fails when runner-image.json has %s", (_label, change, expected) => { + rewriteManifest(out, change); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(expected); + }); + + it("fails when a file differs from the digest runner-image.json records", () => { + appendFileSync(path.join(out, "runner-package/scripts/provision-grok.mjs"), "// changed\n"); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/provision-grok\.mjs \(grokProvisioner\) does not match the digest/); + }); + + it("fails when the image is for other inputs, another commit or another architecture than expected", () => { + const problems = checkRunnerImageLayout(out, { + expectInputsDigest: "f".repeat(64), expectSourceRevision: "b".repeat(40), expectArchitecture: "arm64", + }).join("\n"); + expect(problems).toMatch(/inputs digest is 1{64}, expected f{64}/); + expect(problems).toMatch(/source revision is a{40}, expected b{40}/); + expect(problems).toMatch(/architecture is amd64, expected arm64/); + }); + + it("fails when the daemon is built for another architecture", async () => { + const arm = await image({ source: { machine: 183 } }); + expect(checkRunnerImageLayout(arm).join("\n")).toMatch(/paperclip-runnerd is not a linux\/amd64 executable/); + }); + + it("fails when the daemon is not executable or a file is not readable by every user", () => { + chmodSync(path.join(out, "paperclip-runnerd"), 0o644); + chmodSync(path.join(out, "provider-pack/provider-pack.json"), 0o600); + const problems = checkRunnerImageLayout(out).join("\n"); + expect(problems).toMatch(/paperclip-runnerd is not executable by every user/); + expect(problems).toMatch(/not readable by every user: provider-pack\/provider-pack\.json/); + }); + + describe("Runner build stamp", () => { + it("fails when a build output changed size after the stamp was recorded", () => { + appendFileSync(path.join(out, "runner-package/dist/index.js"), "// later edit\n"); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/build output dist\/index\.js is changed size/); + }); + + it("fails when a recorded build output is gone", () => { + rmSync(path.join(out, "runner-package/dist/testing.js")); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/dist\/testing\.js is missing/); + }); + + it("fails when the stamp was recorded on another architecture", async () => { + const other = await image({ source: { arch: "arm64" } }); + expect(checkRunnerImageLayout(other).join("\n")).toMatch(/stamp was recorded on linux\/arm64, not linux\/x64/); + }); + + it("refuses to describe a build whose stamp names other inputs, and never writes a stamp itself", () => { + const root = path.join(scratch, String(sequence += 1)); + workspace(path.join(root, "workspace"), { digest: "9".repeat(64) }); + const write = () => writeRunnerImageManifest({ + outRoot: path.join(root, "out"), workspaceRoot: path.join(root, "workspace"), identity, platform, libc, sourceRevision: null, + }); + expect(write).toThrow(/built from inputs 9{64}, but the image identity was computed from 2{64}/); + rmSync(buildInputsStampPath(path.join(root, "workspace/packages/paperclip-runner"))); + expect(write).toThrow(/recorded no build stamp/); + }); + }); + + describe("provider pack integrity", () => { + it("fails when an artifact differs from its digest in provider-pack.json", () => { + appendFileSync(path.join(out, "provider-pack/dist/cli/opencode-app-server-proxy.cjs"), "// changed\n"); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/artifact opencodeProxy does not match its digest/); + }); + + it("fails when an artifact is missing", () => { + rmSync(path.join(out, "provider-pack/dist/cli/opencode-app-server-proxy.cjs")); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/artifact opencodeProxy is missing/); + }); + + it("fails when provider assets the manifest names are missing", () => { + rmSync(path.join(out, "provider-pack/provider-assets"), { recursive: true }); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/the provider pack asset tree of pi is missing/); + }); + + it("recomputes the tree digests the manifest records", async () => { + // A file that is not a listed artifact is bound only by its tree digest. + appendFileSync(path.join(out, "provider-pack/provider-assets/pi/linux-x64/pi.js"), "// changed\n"); + expect(checkRunnerImageLayout(out)).toEqual(["the provider pack asset tree of pi does not match its tree digest"]); + const other = await image(); + write(path.join(other, "provider-pack"), "dist/extra.js", "// not built\n"); + expect(checkRunnerImageLayout(other)).toEqual(["the provider pack dist tree does not match its tree digest"]); + const third = await image(); + rmSync(path.join(third, "provider-pack/dist/index.js")); + expect(checkRunnerImageLayout(third).join("\n")).toMatch(/the provider pack dist tree does not match its tree digest/); + }); + + it("fails when the manifest was edited after it was sealed", () => { + const file = path.join(out, "provider-pack/provider-pack.json"); + const pack = JSON.parse(readFileSync(file, "utf8")); + pack.payload.runnerSourceRevision = "c".repeat(40); + writeFileSync(file, JSON.stringify(pack)); + rewriteManifest(out, (m) => { m.sha256.providerPackManifest = `sha256:${sha256(readFileSync(file))}`; }); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/provider-pack\.json digest does not match its payload/); + }); + + it.each<[string, object, RegExp]>([ + ["another commit", { revision: "c".repeat(40) }, /provider pack was built from c{40}, but the image source revision is a{40}/], + ["other inputs", { inputsDigest: "d".repeat(64) }, /runnerInputsDigest does not match/], + ["another architecture", { arch: "arm64" }, /provider pack targets/], + ["another lockfile", { lock: "lockfileVersion: '6.0'\n" }, /lockfile at the image root is not the one the provider pack was installed from/], + ])("fails when the pack was built for %s", async (_label, pack, expected) => { + expect(checkRunnerImageLayout(await image({ pack })).join("\n")).toMatch(expected); + }); + + it("fails when a transport archive or an archived file differs from the receipt", async () => { + appendFileSync(path.join(out, "provider-pack.archives/0.tar.zst"), "x"); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/transport archive 0\.tar\.zst does not match its receipt/); + const other = await image(); + const receipt = path.join(other, "provider-pack.archive.json"); + const parsed = JSON.parse(readFileSync(receipt, "utf8")); + parsed.providerPackDigest = `sha256:${"e".repeat(64)}`; + parsed.files[0].sha256 = "e".repeat(64); + writeFileSync(receipt, JSON.stringify(parsed)); + rewriteManifest(other, (m) => { m.sha256.providerPackArchiveReceipt = `sha256:${sha256(readFileSync(receipt))}`; }); + const problems = checkRunnerImageLayout(other).join("\n"); + expect(problems).toMatch(/transport archives belong to another provider pack/); + expect(problems).toMatch(/archived file node_modules\/node\/bin\/node does not match the provider pack/); + }); + }); + + describe("publication build", () => { + // Another image build can run the same stage inline. That Runner has the + // same inputs, but it is not the published image and must not say it is. + it("is the only build whose pack names the published image", async () => { + expect(JSON.parse(readFileSync(path.join(out, "provider-pack/provider-pack.json"), "utf8")).payload.runnerInputsDigest).toBe(INPUTS); + const inline = await image({ publication: false }); + expect(manifestOf(inline).publication).toBe(false); + expect(manifestOf(inline).sourceRevision).toBe(REVISION); + expect(JSON.parse(readFileSync(path.join(inline, "provider-pack/provider-pack.json"), "utf8")).payload).not.toHaveProperty("runnerInputsDigest"); + expect(checkRunnerImageLayout(inline)).toEqual([]); + expect((await checkProviderPackArchives(inline)).problems).toEqual([]); + }); + + it("refuses a pack that names an image when the build is not a publication build", async () => { + const claiming = await image({ publication: false, pack: { inputsDigest: INPUTS } }); + expect(checkRunnerImageLayout(claiming)).toEqual(["the provider pack records runnerInputsDigest, but this is not a publication build"]); + }); + + it("refuses a publication build whose pack does not name the image", async () => { + const silent = await image({ pack: { inputsDigest: null } }); + expect(checkRunnerImageLayout(silent)).toEqual(["the provider pack runnerInputsDigest does not match the image inputs digest"]); + }); + + it("is required whenever an inputs digest is expected", async () => { + const inline = await image({ publication: false }); + expect(checkRunnerImageLayout(inline, { expectInputsDigest: INPUTS })) + .toEqual(["an inputs digest is expected, but this is not a publication build"]); + expect(checkRunnerImageLayout(out, { expectInputsDigest: INPUTS })).toEqual([]); + }); + + it("cannot be written without a source revision", () => { + const root = path.join(scratch, String(sequence += 1)); + workspace(path.join(root, "workspace")); + expect(() => writeRunnerImageManifest({ + outRoot: path.join(root, "out"), workspaceRoot: path.join(root, "workspace"), identity, platform, libc, sourceRevision: null, publication: true, + })).toThrow(/publication build needs a source revision/); + }); + }); + + describe("transport archive round trip", () => { + // The archives' bytes can match the receipt while the archives do not + // hold the pack. Only extracting them, the way a sandbox does, shows it. + const roundTrip = async (tree: string) => (await checkProviderPackArchives(tree)).problems; + const pack = (...parts: string[]) => path.join(out, "provider-pack", ...parts); + const leftovers = () => readdirSync(tmpdir()).filter((name) => name.startsWith("paperclip-runner-image-archives-")).length; + + /** Replaces one archive and makes the receipt and runner-image.json agree with its bytes. */ + function replaceArchive(tree: string, name: string, bytes: Buffer) { + writeFileSync(path.join(tree, "provider-pack.archives", name), bytes); + const file = path.join(tree, "provider-pack.archive.json"); + const receipt = JSON.parse(readFileSync(file, "utf8")); + const entry = name === "overlay.tar.zst" ? receipt.overlay : receipt.files[Number.parseInt(name, 10)].archive; + entry.sha256 = sha256(bytes); + entry.bytes = bytes.length; + writeFileSync(file, JSON.stringify(receipt)); + rewriteManifest(tree, (m) => { m.sha256.providerPackArchiveReceipt = `sha256:${sha256(readFileSync(file))}`; }); + } + + /** A tar stream with the given members, written by hand so that a member can have a name no tar would write. */ + function tarOf(members: { name: string; type?: "0" | "2" | "5"; mode?: number; content?: string; linkname?: string }[]) { + const blocks: Buffer[] = []; + for (const member of members) { + const body = Buffer.from(member.content ?? ""); + const header = Buffer.alloc(512); + header.write(member.name, 0, 100); + header.write(`${(member.mode ?? 0o644).toString(8).padStart(7, "0")}\0`, 100); + header.write("0000000\0", 108); + header.write("0000000\0", 116); + header.write(`${body.length.toString(8).padStart(11, "0")}\0`, 124); + header.write("00000000000\0", 136); + header.fill(" ", 148, 156); + header.write(member.type ?? "0", 156); + header.write(member.linkname ?? "", 157, 100); + header.write("ustar\u000000", 257); + let sum = 0; + for (const byte of header) sum += byte; + header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148); + blocks.push(header, body, Buffer.alloc((512 - (body.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return Buffer.concat(blocks); + } + + it("passes for the archives the image build's own script writes", async () => { + const before = leftovers(); + const result = await checkProviderPackArchives(out); + expect(result.problems).toEqual([]); + expect(["GNU tar", "bsdtar"]).toContain(result.tar); + // The archives carry the manifest as the builder wrote it, 0600. The + // image has it 0644: that difference is the build's a+rX grant. + expect(leftovers()).toBe(before); + }); + + it("fails for archives that have the recorded bytes but are not archives", async () => { + // This is what the byte comparison alone accepted. + replaceArchive(out, "overlay.tar.zst", Buffer.from("overlay archive")); + expect(checkRunnerImageLayout(out)).toEqual([]); + const before = leftovers(); + expect((await roundTrip(out)).join("\n")).toMatch(/transport archive overlay\.tar\.zst is not a zstd archive/); + expect(leftovers()).toBe(before); + const numbered = await image(); + replaceArchive(numbered, "0.tar.zst", Buffer.from("node archive")); + expect(checkRunnerImageLayout(numbered)).toEqual([]); + expect((await roundTrip(numbered)).join("\n")).toMatch(/transport archive 0\.tar\.zst is not a zstd archive/); + }); + + it("fails for a zstd stream that is not a tar archive", async () => { + replaceArchive(out, "overlay.tar.zst", zstdCompressSync(Buffer.from("this is not a tar archive\n".repeat(400)))); + expect(checkRunnerImageLayout(out)).toEqual([]); + expect((await roundTrip(out)).join("\n")).toMatch(/could not extract the transport archives/); + }); + + it("fails when the archives lack a file or a directory the pack has", async () => { + write(pack(), "dist/late.js", "// written after the archives\n"); + mkdirSync(pack("node_modules/empty")); + expect(await roundTrip(out)).toEqual([ + "the transport archives do not carry these provider pack entries (2): dist/late.js, node_modules/empty", + ]); + }); + + it("fails when the archives carry a file the pack does not have", async () => { + rmSync(pack("provider-assets/pi/linux-x64/pi.js")); + expect(await roundTrip(out)).toEqual([ + "the transport archives carry entries the provider pack does not have (1): provider-assets/pi/linux-x64/pi.js", + ]); + }); + + it("fails when a file's content differs, in the overlay or in an archive of its own", async () => { + appendFileSync(pack("dist/index.js"), "// changed\n"); + const changed = Buffer.from(LARGE); + changed[changed.length - 1] = 0; + writeFileSync(pack("node_modules/node/bin/node"), changed); + expect(await roundTrip(out)).toEqual([ + "the transport archives carry other content (2): dist/index.js, node_modules/node/bin/node", + ]); + }); + + it("fails when a link points elsewhere, or is not a link", async () => { + rmSync(pack("node_modules/.bin/node")); + symlinkSync("../node/bin/other", pack("node_modules/.bin/node")); + expect(await roundTrip(out)).toEqual([ + "the transport archives carry another link target (1): node_modules/.bin/node (-> ../node/bin/node, the pack has -> ../node/bin/other)", + ]); + const other = await image(); + rmSync(path.join(other, "provider-pack/node_modules/.bin/node")); + writeFileSync(path.join(other, "provider-pack/node_modules/.bin/node"), "#!/bin/sh\n"); + expect((await roundTrip(other)).join("\n")).toMatch(/another kind of entry \(1\): node_modules\/\.bin\/node \(link, the pack has a file\)/); + }); + + it.each<[string, string, number, string]>([ + ["a file that gained the executable bit", "dist/index.js", 0o755, "dist/index.js (archived 0644, the pack has 0755)"], + ["a file that lost the executable bit", "node_modules/node/bin/node", 0o644, "node_modules/node/bin/node (archived 0755, the pack has 0644)"], + ["a file that became writable by everyone", "dist/index.js", 0o666, "dist/index.js (archived 0644, the pack has 0666)"], + ["a directory that became private", "dist/cli", 0o700, "dist/cli (archived 0755, the pack has 0700)"], + ["a file the image build's grant was not applied to", "provider-pack.json", 0o600, "provider-pack.json (archived 0600, the pack has 0600)"], + ])("fails for %s", async (_label, relative, mode, expected) => { + chmodSync(pack(...relative.split("/")), mode); + expect(await roundTrip(out)).toEqual([`the transport archives carry other permissions (1): ${expected}`]); + }); + + it("fails when the receipt records another mode than the archive carries", async () => { + const file = path.join(out, "provider-pack.archive.json"); + const receipt = JSON.parse(readFileSync(file, "utf8")); + expect(receipt.files[0].mode).toBe(0o755); + receipt.files[0].mode = 0o644; + writeFileSync(file, JSON.stringify(receipt)); + expect(await roundTrip(out)).toEqual([ + "the receipt records other permissions than the transport archives carry (1): node_modules/node/bin/node (receipt 0644, archived 0755)", + ]); + }); + + it("fails when the archive directory and the receipt disagree, before it extracts anything", async () => { + writeFileSync(path.join(out, "provider-pack.archives/9.tar.zst"), "stray"); + rmSync(path.join(out, "provider-pack.archives/0.tar.zst")); + const result = await checkProviderPackArchives(out); + expect(result.tar).toBeNull(); + expect(result.problems).toEqual([ + "the receipt lists transport archives that are missing (1): 0.tar.zst", + "provider-pack.archives holds files the receipt does not list (1): 9.tar.zst", + ]); + }); + + describe("refuses a member that would be written outside the destination", () => { + const outsideFile = () => path.join(scratch, `escaped-${sequence += 1}.txt`); + + it("by a name that climbs out of it", async () => { + const name = `escaped-${sequence += 1}.txt`; + replaceArchive(out, "overlay.tar.zst", zstdCompressSync(tarOf([{ name: `../${name}`, content: "escaped\n" }]))); + const before = leftovers(); + const problems = await roundTrip(out); + expect(problems.join("\n")).toMatch(/could not extract the transport archives/); + // The destination is a directory directly under the temporary directory. + expect(readdirSync(tmpdir())).not.toContain(name); + expect(leftovers()).toBe(before); + }); + + it("by an absolute name", async () => { + const target = outsideFile(); + replaceArchive(out, "overlay.tar.zst", zstdCompressSync(tarOf([{ name: target, content: "escaped\n" }]))); + expect((await roundTrip(out)).length).toBeGreaterThan(0); + expect(readdirSync(scratch)).not.toContain(path.basename(target)); + }); + + it("through a link that points out of it", async () => { + const directory = path.join(scratch, `outside-${sequence += 1}`); + mkdirSync(directory); + replaceArchive(out, "overlay.tar.zst", zstdCompressSync(tarOf([ + { name: "exit", type: "2", linkname: directory }, + { name: "exit/escaped.txt", content: "escaped\n" }, + ]))); + expect((await roundTrip(out)).length).toBeGreaterThan(0); + expect(readdirSync(directory)).toEqual([]); + }); + }); + + it("is part of the check command, which says which tar extracted the archives", async () => { + const check = (tree: string) => spawnSync(process.execPath, [layoutScript, "check", tree], { encoding: "utf8" }); + const passed = check(out); + expect(passed.status).toBe(0); + expect(passed.stdout).toMatch(/The transport archives were extracted with (GNU tar, as a sandbox extracts them,|bsdtar) and match the provider pack/); + // A tree the layout check alone accepts. + replaceArchive(out, "overlay.tar.zst", Buffer.from("overlay archive")); + expect(checkRunnerImageLayout(out)).toEqual([]); + const failed = check(out); + expect(failed.status).toBe(1); + expect(failed.stderr).toMatch(/transport archive overlay\.tar\.zst is not a zstd archive/); + expect(failed.stdout).not.toMatch(/passed/); + // A tree without a pack has nothing to extract, and the command says so. + const unstamped = spawnSync(process.execPath, [layoutScript, "check", await image({ stamped: false }), "--allow-unstamped"], { encoding: "utf8" }); + expect(unstamped.status).toBe(0); + expect(unstamped.stdout).toMatch(/no provider pack, so there are no transport archives to extract/); + }); + }); + + describe("paths that resolve outside the tree", () => { + // A link to a file with the right bytes somewhere else on the machine + // must not vouch for a file the image does not contain. + const outside = () => { + const directory = path.join(scratch, String(sequence += 1)); + mkdirSync(directory, { recursive: true }); + return directory; + }; + + it("refuses a pack artifact that is a link out of the pack", () => { + const artifact = path.join(out, "provider-pack/dist/cli/opencode-app-server-proxy.cjs"); + const elsewhere = path.join(outside(), "proxy.cjs"); + renameSync(artifact, elsewhere); + symlinkSync(elsewhere, artifact); + expect(readFileSync(artifact, "utf8")).toBe("opencodeProxy\n"); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/artifact opencodeProxy resolves outside the pack/); + }); + + it("refuses an artifact path that climbs out of the pack", () => { + const file = path.join(out, "provider-pack/provider-pack.json"); + const pack = JSON.parse(readFileSync(file, "utf8")); + pack.payload.artifacts.nodeCommand.path = "../paperclip-runnerd"; + pack.digest = `sha256:${sha256(canonicalJson(pack.payload))}`; + writeFileSync(file, JSON.stringify(pack)); + expect(checkRunnerImageLayout(out).join("\n")).toMatch(/artifact nodeCommand resolves outside the pack/); + }); + + it("refuses an archived file and a transport archive that are links out of the tree", () => { + const archived = path.join(out, "provider-pack/node_modules/node/bin/node"); + const elsewhere = outside(); + renameSync(archived, path.join(elsewhere, "node")); + symlinkSync(path.join(elsewhere, "node"), archived); + const archive = path.join(out, "provider-pack.archives/overlay.tar.zst"); + renameSync(archive, path.join(elsewhere, "overlay.tar.zst")); + symlinkSync(path.join(elsewhere, "overlay.tar.zst"), archive); + const problems = checkRunnerImageLayout(out).join("\n"); + expect(problems).toMatch(/archived file node_modules\/node\/bin\/node resolves outside the pack/); + expect(problems).toMatch(/transport archive overlay\.tar\.zst resolves outside the image/); + }); + + it("refuses a documented path reached through a linked directory", () => { + const source = path.join(out, "runner-package/src"); + const elsewhere = path.join(outside(), "src"); + cpSync(source, elsewhere, { recursive: true }); + rmSync(source, { recursive: true }); + symlinkSync(elsewhere, source); + const problems = checkRunnerImageLayout(out).join("\n"); + expect(problems).toMatch(/documented path runner-package\/src\/providers\/grok\/platforms\.json \(grokPlatforms\) resolves outside the image/); + }); + + it("accepts a link that stays inside the pack, as pnpm's layout has them", () => { + const pack = path.join(out, "provider-pack"); + const real = path.join(pack, "node_modules/.pnpm/node@24/node_modules/node"); + mkdirSync(path.dirname(real), { recursive: true }); + renameSync(path.join(pack, "node_modules/node"), real); + symlinkSync(path.relative(path.join(pack, "node_modules"), real), path.join(pack, "node_modules/node")); + expect(checkRunnerImageLayout(out)).toEqual([]); + }); + }); + + describe("command line", () => { + const check = (...args: string[]) => spawnSync(process.execPath, [layoutScript, "check", ...args], { encoding: "utf8" }); + + it("passes for a valid tree and fails for a wrong expectation", () => { + expect(check(out, "--expect-inputs-digest", INPUTS, "--expect-source-revision", REVISION, "--expect-architecture", "amd64").status).toBe(0); + const wrong = check(out, "--expect-architecture", "arm64"); + expect(wrong.status).toBe(1); + expect(wrong.stderr).toMatch(/architecture is amd64, expected arm64/); + }); + + it.each<[string, string[], RegExp]>([ + ["an empty inputs digest", ["--expect-inputs-digest", ""], /--expect-inputs-digest needs a value/], + ["an empty source revision", ["--expect-source-revision", ""], /--expect-source-revision needs a value/], + ["an empty architecture", ["--expect-architecture", ""], /--expect-architecture needs a value/], + ["a flag with no value", ["--expect-inputs-digest"], /--expect-inputs-digest needs a value/], + ["a flag whose value is another flag", ["--expect-inputs-digest", "--allow-unstamped"], /--expect-inputs-digest needs a value/], + ["a misspelt flag", ["--expect-input-digest", INPUTS], /check does not take --expect-input-digest/], + ["a flag of the other command", ["--identity", "x"], /check does not take --identity/], + ["a repeated flag", ["--expect-architecture", "amd64", "--expect-architecture", "amd64"], /given twice/], + ["a malformed inputs digest", ["--expect-inputs-digest", "abc"], /must be 64 hexadecimal characters/], + ["an abbreviated source revision", ["--expect-source-revision", "abc1234"], /must be a full Git SHA/], + ["an unknown architecture", ["--expect-architecture", "x64"], /must be amd64 or arm64/], + ])("rejects %s instead of treating the expectation as not given", (_label, args, expected) => { + const result = check(out, ...args); + expect(result.status).toBe(1); + expect(result.stderr).toMatch(expected); + expect(result.stdout).not.toMatch(/passed/); + }); + + it("needs exactly one directory, and a known command", () => { + expect(check().status).toBe(1); + expect(check(out, out).status).toBe(1); + expect(spawnSync(process.execPath, [layoutScript, "verify", out], { encoding: "utf8" }).status).toBe(1); + }); + + it("parses the flags each command knows", () => { + expect(parseLayoutArguments("check", ["tree", "--allow-unstamped", "--expect-architecture", "arm64"])).toEqual({ + positional: ["tree"], flags: { "allow-unstamped": true, "expect-architecture": "arm64" }, + }); + expect(() => parseLayoutArguments("write", ["--out", "o", "--source-revision", ""])).toThrow(/--source-revision needs a value/); + expect(parseLayoutArguments("write", ["--out", "o", "--publication"]).flags).toEqual({ out: "o", publication: true }); + expect(() => parseLayoutArguments("check", ["tree", "--publication"])).toThrow(/check does not take --publication/); + expect(() => parseLayoutArguments("write", ["--expect-architecture", "arm64"])).toThrow(/write does not take/); + }); + }); + + describe("a build without a source revision", () => { + it("has the daemon and the Runner build but no pack, and is not a complete image", async () => { + const unstamped = await image({ stamped: false }); + const manifest = manifestOf(unstamped); + expect(manifest.sourceRevision).toBeNull(); + expect(manifest.providerPack).toBeNull(); + expect(manifest.inputsDigest.digest).toBe(INPUTS); + expect(checkRunnerImageLayout(unstamped).join("\n")).toMatch(/has no source revision/); + expect(checkRunnerImageLayout(unstamped, { allowUnstamped: true })).toEqual([]); + // It is still checked: the daemon and the stamp must hold. + appendFileSync(path.join(unstamped, "runner-package/dist/index.js"), "// later edit\n"); + expect(checkRunnerImageLayout(unstamped, { allowUnstamped: true }).join("\n")).toMatch(/changed size/); + }); + }); + + it("writes nothing at the image root that the documented layout does not list", () => { + const documented = new Set(Object.values(RUNNER_IMAGE_PATHS).map((relative) => (relative as string).split("/")[0])); + expect(new Set(readdirSync(out))).toEqual(documented); + expect([...documented].sort()).toEqual(["bundles", "paperclip-runnerd", "pnpm-lock.yaml", "provider-pack", + "provider-pack.archive.json", "provider-pack.archives", "runner-image.json", "runner-package"]); + }); +}); diff --git a/server/src/__tests__/runner-image-workflow.test.ts b/server/src/__tests__/runner-image-workflow.test.ts new file mode 100644 index 00000000000..36cc97d438a --- /dev/null +++ b/server/src/__tests__/runner-image-workflow.test.ts @@ -0,0 +1,89 @@ +import { readFileSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; +import { RUNNER_IMAGE_CONTEXT_INPUTS } from "../../../scripts/runner-image-identity.mjs"; + +/** + * Security properties of the Runner image workflow. The build runs dependency + * lifecycle scripts, so what the jobs may do matters more than how their + * steps are worded: these tests pin permissions, credentials and triggers, + * not step names or order. + */ + +const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", ".."); +const workflow = readFileSync(path.join(repoRoot, ".github", "workflows", "runner-image.yml"), "utf8"); +const mergeReview = readFileSync(path.join(repoRoot, ".github", "workflows", "pr-merge-review.yml"), "utf8"); +const smoke = readFileSync(path.join(repoRoot, "docker", "runner-image", "Dockerfile.smoke"), "utf8"); + +/** Each job's text, by name. */ +const jobs = Object.fromEntries(workflow.slice(workflow.indexOf("\njobs:\n")).split(/\n(?= {2}[a-z_-]+:\n)/).slice(1) + .map((text) => [/^ {2}([a-z_-]+):/.exec(text)![1], text])); +const permissions = (job: string) => + [.../\n {4}permissions:\n((?: {6}.+\n)+)/.exec(job)![1].matchAll(/^ {6}([a-z-]+): (\w+)/gm)].map((match) => `${match[1]}: ${match[2]}`); +/** The shell of every `run:`, block or single line. */ +const scripts = [...workflow.matchAll(/^( +)run: (\|\n((?:\1 {2,}.*\n|\n)+)|.+\n)/gm)].map((match) => match[3] ?? match[2]); + +describe("Runner image workflow", () => { + it("grants nothing at the workflow level and only read access to contents in each job", () => { + expect(workflow).toMatch(/^permissions: \{\}$/m); + expect(Object.keys(jobs)).toEqual(["identity", "build"]); + for (const job of Object.values(jobs)) expect(permissions(job)).toEqual(["contents: read"]); + }); + + it("has no credential, no registry access and no way to publish", () => { + expect(workflow).not.toMatch(/github\.token|secrets\.|GITHUB_TOKEN|docker\/login-action|packages:|id-token|attestations/); + expect(workflow).not.toMatch(/--push|push=true|skopeo|imagetools|type=image|type=registry|cache-to|cache-from|type=gha/); + const triggers = workflow.slice(workflow.indexOf("\non:\n"), workflow.indexOf("\npermissions:")); + expect([...triggers.matchAll(/^ {2}([a-z_]+):/gm)].map((match) => match[1])).toEqual(["pull_request", "workflow_dispatch"]); + }); + + it("pins every action by commit and keeps expressions out of shell scripts", () => { + const uses = [...workflow.matchAll(/^\s*(?:- )?uses: (\S+)/gm)].map((match) => match[1]); + expect(uses.length).toBeGreaterThan(5); + for (const action of uses) expect(action).toMatch(/^[\w.-]+\/[\w./-]+@[0-9a-f]{40}$/); + // An expression in a script is substituted before the shell parses it. + expect(scripts.length).toBeGreaterThan(5); + for (const script of scripts) expect(script).not.toContain("${{"); + }); + + it("runs for a pull request that changes any input of the image identity", () => { + const paths = [...workflow.matchAll(/^ {6}- (\S+)$/gm)].map((match) => match[1]); + const covered = (file: string) => paths.some((pattern) => pattern === file + || (pattern.endsWith("/**") && (file === pattern.slice(0, -3) || file.startsWith(pattern.slice(0, -2))))); + // .dockerignore is not in the identity, but it decides which files the build receives. + for (const input of ["Dockerfile", ".dockerignore", ".github/workflows/runner-image.yml", "docker/runner-image/Dockerfile.smoke", + ...RUNNER_IMAGE_CONTEXT_INPUTS]) { + expect(covered(input), input).toBe(true); + } + }); + + it("is registered with the merge-review notifier under its own name", () => { + const name = /^name: (.+)$/m.exec(workflow)![1]; + const listed = /workflow_run:\n {4}workflows:\n((?: {6}- .+\n)+)/.exec(mergeReview)![1].split("\n").filter(Boolean).map((line) => line.trim().slice(2)); + expect(listed).toContain(name); + }); +}); + +describe("Runner image smoke matrix", () => { + it("runs the daemon on every consumer base, each pinned by digest", () => { + const bases = [...smoke.matchAll(/^FROM (\S+) AS (\S+)$/gm)].map((match) => match[1]).filter((base) => base !== "scratch"); + expect(bases.map((base) => base.slice(0, base.indexOf("@")))).toEqual([ + "debian:bookworm-slim", + "debian:trixie-slim", + "node:24-trixie-slim", + "python:3.13-slim-trixie", + "daytonaio/sandbox:0.8.0", + ]); + for (const base of bases) expect(base).toMatch(/@sha256:[0-9a-f]{64}$/); + expect(smoke.match(/^RUN paperclip-runnerd --build-metadata /gm)).toHaveLength(bases.length); + // The final stage reads a result from every base, so none can be skipped. + expect(smoke.slice(smoke.indexOf("FROM scratch AS smoke")).match(/^COPY --from=smoke-/gm)).toHaveLength(bases.length); + }); + + it("reads the Runner image only the way a consumer may", () => { + const copies = [...smoke.matchAll(/^COPY --from=runner-artifacts (.+)$/gm)].map((match) => match[1]); + expect(new Set(copies)).toEqual(new Set(["/paperclip-runnerd /usr/local/bin/paperclip-runnerd"])); + expect(smoke).not.toMatch(/^FROM runner-artifacts/m); + }); +});