diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index af433a7..7c83e59 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -45,7 +45,8 @@ jobs: fi - run: go vet ./... # The tests need git. GitHub sets CI=true, and then a test fails - # instead of skips when git is missing. + # instead of skips when git is missing. The tests of install.sh + # (install_linux_test.go) run it against a fake release. - run: git --version - run: go test -race ./... - name: Build static binaries @@ -97,6 +98,23 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - name: shellcheck install.sh + # A fixed release of ShellCheck, checked by its SHA-256. Dependabot + # does not update it. Update it by hand: the version and the SHA-256 + # of shellcheck-VERSION.linux.x86_64.tar.xz together. + env: + SHELLCHECK_VERSION: v0.11.0 + SHELLCHECK_SHA256: 8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198 + run: | + set -euo pipefail + dir="${RUNNER_TEMP}/shellcheck" + mkdir -p "$dir" + curl --proto '=https' --tlsv1.2 -fsSL --retry 3 -o "$dir/shellcheck.tar.xz" \ + "https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION}/shellcheck-${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" + echo "${SHELLCHECK_SHA256} $dir/shellcheck.tar.xz" | sha256sum --strict -c - + tar -xJf "$dir/shellcheck.tar.xz" -C "$dir" + "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --version + "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version-file: go.mod diff --git a/AGENTS.md b/AGENTS.md index 3171651..7aaddc6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,9 @@ change code. They are the rules the code must follow. - `internal/gate/` - `run`, `apply` and `status` (DESIGN.md sections 7, 9, 10, 13). - `contrib/` - example systemd units and example configs. +- `install.sh` - installs or updates a release on a host, after its checks + (DESIGN.md section 16). Its tests are `install_linux_test.go`, at the + root. CI runs a pinned ShellCheck on it. - `test/e2e/` - the end-to-end test. Build tag `e2e`. - `docs/releasing.md` - how releases are made and checked. Only the owner merges a release pull request (`chore(main): release …`). diff --git a/DESIGN.md b/DESIGN.md index bbdbbea..1ef9968 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -568,8 +568,80 @@ bare repo with two commits, runs `pullgate run`, the listener against the fake Telegram server, a tap, `pullgate apply`, and checks that the second commit was applied. +The tests of `install.sh` (`install_linux_test.go`, at the root) run the +script with `/bin/sh` against a fake release: a fake `curl`, `uname`, `gh` +and `pullgate`. They never use the network. They show that the script +installs nothing when a check fails (section 16), and that it installs when +all checks pass. CI also runs a pinned ShellCheck on the script. + ## 15. Not in version 0.1 -- Self-update of pullgate. +- Self-update of pullgate. `install.sh` updates it only when root runs + the script (section 16). - Signed commits (`git verify-commit`). - A web UI. + +## 16. The install script + +`install.sh`, at the root of the repo, installs a release, or updates one. +It is a POSIX `sh` script. Root runs it on the host itself: + +```sh +sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] +``` + +All the work is in functions. Only the last line starts `main`, so a +download that stops in the middle runs nothing. The steps: + +1. Clean the environment: remove `TAR_OPTIONS`, `GZIP`, `CURL_HOME`, the + `SSL_CERT_*`, `OPENSSL_*` and `LD_*` variables, `GCONV_PATH`, + `GLIBC_TUNABLES`, `GODEBUG`, `CDPATH`, `IFS` and more (the list and the + reasons are in `clean_env` of the script). Set `LC_ALL=C`. As root, set + `PATH=/usr/sbin:/usr/bin:/sbin:/bin`. pullgate and gh run with a time + limit (`timeout`): 60 seconds, and 300 seconds for + `gh attestation verify`. curl has its own limit. +2. Read the arguments. `--version` must be `X.Y.Z`. A wrong argument + exits with 64. +3. Check the platform: Linux on amd64 or arm64 only. +4. Check the paths: only root may change the bin directory + (default `/usr/local/bin`), each directory above it, the old binary and + the `--gh` file. The old binary `DIR/pullgate` must be a regular file or + missing, never a link. A directory that others can write may pass only + above the checked path, and only with the sticky bit (as `/tmp`). +5. Make a temporary directory with `mktemp -d` in `TMPDIR` (default + `/tmp`). Check `TMPDIR`, each directory above it, and the new directory. +6. Ask the GitHub API for the newest release, or for the release of + `--version`. Its tag must be `vX.Y.Z` of that version. +7. Run the old binary with `version`. The same version: nothing to do, + exit 0, unless `--reinstall`. A newer installed version: nothing to do, + unless `--version` asks for the older one; then it says that this is a + downgrade. An unknown version (`pullgate dev`, no output, or it does not + run): fail, unless `--reinstall`. +8. Download `pullgate__linux_.tar.gz`, `SHA256SUMS` and + `pullgate_.sigstore.json`. Every download uses + `curl -q --proto '=https' --tlsv1.2` and has a size limit: 1 MiB for the + API answer, `SHA256SUMS` and the bundle; 64 MiB for a tarball. +9. `SHA256SUMS` must have exactly one line for the tarball, and the SHA-256 + must match. +10. Get gh: the `--gh` file (gh 2.93.0 or newer), or gh 2.102.0, downloaded + and checked against the SHA-256 for this CPU that is written in the + script. gh runs with no token and an empty config. +11. Run `gh attestation verify` on the tarball with the bundle, + `--repo code6x/pullgate`, `--cert-identity + https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main` + and `--deny-self-hosted-runners`. +12. Take only `pullgate` out of the tarball. Run `pullgate version` from the + temporary directory. It must print `pullgate X.Y.Z` of the version + asked for, and nothing else. +13. Copy it into the bin directory under a new name, mode 0755, owner + root. Run `pullgate version` there again. Write it to the disk + (`sync`), then rename it over the old binary. The rename is atomic: a + new process gets the old file or the new one. +14. Print what to restart. The script restarts nothing. + `pullgate-listen.service` runs the old binary until it is restarted. + The timers and path units start a new process each time, so they get + the new binary at their next start. + +A trap removes the temporary directory and a new file that was not renamed +yet, at every exit. A failure exits with 1, and its last line says that +nothing was installed. What the script trusts: THREAT-MODEL.md, T17. diff --git a/README.md b/README.md index e551696..86ae644 100644 --- a/README.md +++ b/README.md @@ -41,17 +41,48 @@ path unit ─> pullgate apply NAME (root) ## Install -Download a release and check it as [docs/releasing.md](docs/releasing.md) -says (section "Verify a download"), or build it with Go 1.26 or newer: +pullgate runs on Linux, on amd64 or arm64. There are three ways to get the +binary. + +**With the install script** (as root, on the host itself). Download the +script, read it, then run it: + +```sh +curl --proto '=https' --tlsv1.2 -fsSL -o /root/install.sh https://raw.githubusercontent.com/code6x/pullgate/main/install.sh +less /root/install.sh +sh /root/install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] +``` + +It installs the newest release, or the one of `--version`, as +`/usr/local/bin/pullgate` (or `DIR/pullgate`). It installs nothing unless +every check passes: the SHA-256 in `SHA256SUMS`, the build attestation of +the release (with `gh attestation verify`), and the version that the new +binary prints. It needs `curl`, `tar`, `gzip`, `sed` and GNU coreutils. Without +`--gh`, it downloads a pinned gh and checks its SHA-256. It replaces the old +binary only in the last step, and restarts nothing: it prints what to +restart. Run it again to update. `--reinstall` installs the same version +again, or replaces a build of unknown version. Exit codes: 0 done or nothing +to do, 1 failure (nothing was installed), 64 wrong usage. To get the +script of one release, put its tag (`vX.Y.Z`) in the URL instead of `main`. +To start it with a clean environment, run it as +`env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh /root/install.sh`. What it does and +what it trusts: [DESIGN.md](DESIGN.md) section 16 and +[THREAT-MODEL.md](THREAT-MODEL.md) T17. + +**By hand.** Download a release and check it as +[docs/releasing.md](docs/releasing.md) says (section "Verify a download"). +Then, as root: `install -m 0755 pullgate /usr/local/bin/pullgate`. + +**From the source**, with Go 1.26 or newer. Then install it as above: ```sh CGO_ENABLED=0 go build -trimpath -o pullgate ./cmd/pullgate ``` -Then, as root: +Then, as root, make the users and the directories, and copy the units from +[contrib/systemd/](contrib/systemd/): ```sh -install -m 0755 pullgate /usr/local/bin/pullgate useradd --system --no-create-home --shell /usr/sbin/nologin pullgate # One check user per instance, never the listener user: useradd --system --no-create-home --shell /usr/sbin/nologin pullgate-check-config-repo diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index c8fbfe5..1df3225 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -39,6 +39,7 @@ on the host, out of reach of the repo. | the network | Not trusted. SSH with a pinned host key protects the fetch. | | other local users | Not trusted. | | the `apply` and `health` commands | Trusted: the owner wrote them. They run as root on the approved tree. | +| GitHub, the release workflow on `main`, and the gh that `install.sh` pins | Trusted to build and serve the release that `install.sh` installs (T16, T17). | ## 4. What pullgate promises @@ -299,7 +300,64 @@ move one, releases are immutable, and the `release` environment needs the owner's approval. The build job is read-only and checks that the tag is the commit of the run. Each tarball has a SHA-256 in `SHA256SUMS` and a build provenance attestation tied to `release.yml` on `main`. Check both before -you install (docs/releasing.md, "Verify a download"). +you install (docs/releasing.md, "Verify a download"), or let `install.sh` +check them (T17). + +### T17. A bad install path + +*Attack.* `install.sh` runs as root and puts a binary that root runs later. +An attacker tries to make it install a file that the release workflow did +not build, or an older build under a newer name. Or a local user changes a +file or a directory that the script uses while it runs. Or the +environment of root changes what `tar`, `curl` or `gh` do. + +*What the script trusts.* + +- **GitHub**: to serve the release files and the answer of its API over + HTTPS, and to run the release workflow on its own runners. +- **The release workflow identity**: only + `https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main`, + on a runner that GitHub hosts, may have built the tarball. Sigstore's + public trusted root says whether the attestation is valid. +- **The pinned gh**: gh 2.102.0, checked against a SHA-256 for each CPU that + is written in the script. Or a gh that the owner gives with `--gh`: it + must be 2.93.0 or newer, and only root may change it. +- **The script itself**: the owner downloads it over HTTPS and reads it + before running it. +- **The host**: root, and the programs in `/usr/sbin:/usr/bin:/sbin:/bin`. + +*Defense.* (DESIGN.md section 16.) The script installs nothing unless every +check passes: exactly one line in `SHA256SUMS` for the tarball, and its +SHA-256 matches; `gh attestation verify` with the bundle of the release, +`--repo code6x/pullgate`, the identity above and +`--deny-self-hosted-runners`; the new binary prints `pullgate X.Y.Z` of the +version asked for. The attestation proves which workflow built a file, not +its version, so the version check stops an older build under a newer name. +The new binary runs only after the attestation passed. Every download has +a size limit, uses HTTPS only with TLS 1.2 or newer, and reads no +`.curlrc`. The script removes a list of variables that change `tar`, +`gzip`, `curl`, OpenSSL, gh, name lookups, libc and the dynamic loader, sets +`LC_ALL=C`, and as root uses a fixed `PATH`. pullgate and gh run with a time +limit (`timeout`), and curl has its own. It writes the new file to the disk before the rename. gh runs with no token and an empty config. Only root may +change the bin directory, the old binary, `TMPDIR`, the new temporary +directory and the `--gh` file, and each directory above them. A directory +above them that others can write is accepted only with the sticky bit, as +`/tmp` has. The old +binary must be a regular file, never a link. The new file replaces the old +one by a rename in the same directory, as the last step. + +*What is left.* Whoever controls the release workflow on `main` (T16), or +GitHub itself, can ship a binary that passes. The script cannot check +itself: a changed copy of `install.sh` can do anything, so read it before +you run it. The list of removed variables is a block list: a variable that +is not on it, or one that acts before the first line runs (such as +`SHELLOPTS` when `sh` is bash), still reaches the programs. Who controls +root's environment controls root already; to be sure, start the script +with `env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh install.sh`. The proxy +variables stay on purpose: TLS and the attestation protect what comes +through a proxy. The old binary runs once, as root, to print its version; only +root can change it, so this gives nothing new to an attacker. The script +restarts nothing. ## 6. Out of scope diff --git a/docs/releasing.md b/docs/releasing.md index a01e1c2..55553f4 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -88,3 +88,6 @@ gh attestation verify "pullgate_${VERSION}_linux_${ARCH}.tar.gz" \ ``` Both checks must say OK before you install the binary. + +`install.sh` makes the same checks, and checks the version of the new +binary too (README.md, section "Install"). diff --git a/install.sh b/install.sh new file mode 100644 index 0000000..9bd0c87 --- /dev/null +++ b/install.sh @@ -0,0 +1,722 @@ +#!/bin/sh +# install.sh installs pullgate from a release on GitHub, or updates it. +# +# Run it as root on the host itself. README.md (section "Install") shows +# how to get and run it, DESIGN.md (section 16) says what it does, and +# THREAT-MODEL.md (T17) says what it trusts. +# +# sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] +# +# It installs nothing unless every check passes: +# - only root can change the bin directory, the old file, the temporary +# directory and the gh of --gh (when the script does not run as root, +# the user who runs it may too); +# - the release has the tag vX.Y.Z of the version; +# - the SHA-256 of the tarball is the one in SHA256SUMS of the release; +# - gh attestation verify, with the bundle file of the release, says that +# the release workflow of code6x/pullgate on main built the tarball, on +# a runner that GitHub hosts; +# - the new pullgate says that it is the version asked for. The +# attestation proves which workflow built a file, not its version, so +# this check stops an older build that was published under a newer +# name. +# +# All the work is in functions, and only the last line starts it. So if a +# download stops in the middle, nothing runs. +# +# Exit codes: 0 done or nothing to do, 1 failure, 64 wrong usage. + +set -eu + +# The gh that checks the attestation when --gh is not given, and the +# SHA-256 of its tarball for each CPU. The SHA-256s are the lines of +# gh_2.102.0_checksums.txt of that release, and both tarballs passed +# "gh attestation verify --repo cli/cli" on 2026-10-17. Change the version +# and both SHA-256s together, and check them in the same way. +gh_version=2.102.0 +gh_sha256_amd64=bb766f710eef8ede859c18578c72c327597cd4c8a85b06001b1f3843c6019386 +gh_sha256_arm64=7862c86c72f43df3a2d93ddde6f473285b4e2af61b494849846827e513ef6484 + +# The oldest gh that --gh may name. Older versions have known bugs in +# gh attestation verify (GHSA-fgw4-v983-mgp8, GHSA-8xvp-7hj6-mcj9). Newer +# advisories (GHSA-mm27-mwq9-fr5g, GHSA-wjmr-j3rp-mh2g, GHSA-4mq3-hpgx-9cx8) +# are about --signer-repo, --signer-workflow and --source-ref only, which +# this script does not use. +gh_min_version=2.93.0 + +repo=code6x/pullgate + +# Only the release workflow on main may have built the tarball. This is +# the identity of docs/releasing.md, "Verify a download". +cert_identity=https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main + +# As root, the script runs only the programs of these directories. +root_path=/usr/sbin:/usr/bin:/sbin:/bin + +# Time limits, in seconds, of the programs that the script runs, other +# than curl (it has its own). timeout sends TERM, and KILL 10 seconds +# later. +max_run=60 # pullgate version, gh --version +max_verify=300 # gh attestation verify: it gets the trusted root of Sigstore online + +# Size limits of the downloads, in bytes. An older curl checks only the +# size that the server announces. +max_small=1048576 # 1 MiB: the answer of the API, SHA256SUMS, the bundle +max_big=67108864 # 64 MiB: the tarballs of pullgate and of gh + +usage() { + cat <&2 + exit 1 +} + +# usage_error prints the usage, and the last line says why the usage is +# wrong. It exits with 64. +usage_error() { + usage >&2 + printf 'pullgate: %s (exit 64)\n' "$*" >&2 + exit 64 +} + +# cleanup removes the temporary directory and a new file that was not +# renamed yet. It runs at every exit, also after a failure. It must return +# 0: under set -e, a failed trap would change the exit code. +cleanup() { + if [ -n "$tmp_target" ]; then + rm -f "$tmp_target" || : + fi + if [ -n "$tmp" ]; then + rm -rf "$tmp" || : + fi + return 0 +} + +# on_signal ends the script after a signal. Its last line says whether the +# new file was already in place. +on_signal() { + if [ -n "$renamed" ]; then + printf 'pullgate: stopped by a signal after the new file was installed as %s; run %s version to check it (exit 1)\n' "$target" "$target" >&2 + exit 1 + fi + if [ -n "$renaming" ]; then + printf 'pullgate: stopped by a signal during the rename; the new file may be installed as %s; run %s version to check it (exit 1)\n' "$target" "$target" >&2 + exit 1 + fi + die "stopped by a signal; run the script again" +} + +# check_tools stops early when timeout is not the one of GNU coreutils +# (busybox timeout has no --foreground). Later errors would else point the +# wrong way, for example to an unknown installed version. +check_tools() { + timeout --foreground 10 true >/dev/null 2>&1 || + die "timeout --foreground does not work; install GNU coreutils and run the script again" +} + +# clean_env removes the variables that change what the programs of the +# script do in a way that is not safe here, sets LC_ALL=C, and sets uid. +# As root, PATH becomes root_path, so that only the programs of the system +# run. The variables: +# - TAR_OPTIONS: options for tar, such as --to-command or +# --checkpoint-action=exec, which run commands as root; +# - GZIP: options for gzip; +# - POSIXLY_CORRECT: changes how the GNU programs read their arguments; +# - CURL_HOME: where curl finds .curlrc (download gives curl -q too); +# - CURL_CA_BUNDLE, SSL_CERT_FILE, SSL_CERT_DIR: the TLS certificates +# that curl and gh trust; +# - SSLKEYLOGFILE: a file that curl writes the TLS keys to; +# - OPENSSL_CONF, OPENSSL_MODULES, OPENSSL_ENGINES: the config of +# OpenSSL, which curl reads at its start, and the places of the +# modules it loads. A config can name any library to load as a +# provider; +# - LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, GCONV_PATH: code that each +# program loads; +# - LD_DEBUG, LD_DEBUG_OUTPUT, LD_PROFILE, LD_PROFILE_OUTPUT, +# GLIBC_TUNABLES, MALLOC_TRACE, MALLOC_CHECK_, MALLOC_PERTURB_: files +# that the loader and libc write as root, and how they work; +# - HOSTALIASES, RES_OPTIONS, LOCALDOMAIN: how names are looked up; +# - GODEBUG: how gh, a Go program, works (for example its TLS); +# - GH_DEBUG, GH_PAGER, PAGER, GH_BROWSER, BROWSER: what gh prints and +# runs; +# - CDPATH and IFS: how cd finds a directory and how the shell splits +# words. +# The proxy variables (https_proxy and the others) stay: some hosts need a +# proxy, and TLS and the attestation protect what comes through it. +# Variables that act before the first line runs (for example SHELLOPTS +# when sh is bash) cannot be removed here. To start with a clean +# environment, run: env -i PATH=$root_path sh install.sh +clean_env() { + unset TAR_OPTIONS GZIP POSIXLY_CORRECT CURL_HOME CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR \ + SSLKEYLOGFILE OPENSSL_CONF OPENSSL_MODULES OPENSSL_ENGINES \ + LD_PRELOAD LD_LIBRARY_PATH LD_AUDIT GCONV_PATH \ + LD_DEBUG LD_DEBUG_OUTPUT LD_PROFILE LD_PROFILE_OUTPUT GLIBC_TUNABLES MALLOC_TRACE MALLOC_CHECK_ MALLOC_PERTURB_ \ + HOSTALIASES RES_OPTIONS LOCALDOMAIN GODEBUG GH_DEBUG GH_PAGER PAGER GH_BROWSER BROWSER CDPATH IFS + LC_ALL=C + export LC_ALL + uid=$( + PATH=$root_path + export PATH + id -u + ) || die "cannot run id -u; check that $root_path has the program id" + case $uid in + '' | *[!0-9]*) die "id -u does not print a user ID; check the program id in $root_path" ;; + esac + owners=root + if [ "$uid" = 0 ]; then + PATH=$root_path + export PATH + else + owners="root or user $uid" + fi +} + +# is_number reports whether $1 is a number of at most 9 digits, without a +# leading zero. +is_number() { + case $1 in + 0) return 0 ;; + '' | 0* | *[!0-9]* | ??????????*) return 1 ;; + esac + return 0 +} + +# is_version reports whether $1 is a version X.Y.Z: three numbers, and +# nothing else. +is_version() { + case $1 in + *.*.*.* | *[!0-9.]*) return 1 ;; + *.*.*) ;; + *) return 1 ;; + esac + v_rest=${1#*.} + is_number "${1%%.*}" && is_number "${v_rest%%.*}" && is_number "${v_rest#*.}" +} + +# compare_versions sets cmp to -1, 0 or 1 when the version $1 is older +# than, the same as, or newer than the version $2. Both must pass +# is_version, so each part is a small number. +compare_versions() { + cmp_a=$1 + cmp_b=$2 + cmp=0 + for _ in 1 2 3; do + if [ "${cmp_a%%.*}" -lt "${cmp_b%%.*}" ]; then + cmp=-1 + return 0 + fi + if [ "${cmp_a%%.*}" -gt "${cmp_b%%.*}" ]; then + cmp=1 + return 0 + fi + cmp_a=${cmp_a#*.} + cmp_b=${cmp_b#*.} + done +} + +# real_dir sets real to the path of the directory $1 without links, . or +# .. in it. The script then uses this path, so a link that someone changes +# later does not matter. +real_dir() { + real=$(cd -P -- "$1" && pwd -P) || die "cannot find the directory $1; check the path" +} + +# check_entry checks that only $owners can change the path $1: its owner +# must be one of them, and group and others must not be able to write to +# it. With $2 "shared", a directory may let them write when it has the +# sticky bit, as /tmp does: then they cannot rename or remove what is not +# theirs in it. +check_entry() { + ce_stat=$(stat -c '%u %a' "$1") || die "cannot read the owner and the mode of $1; check that it exists and that stat works" + ce_owner=${ce_stat%% *} + ce_mode=${ce_stat#* } + case $ce_owner$ce_mode in + '' | *[!0-9]*) die "cannot read the owner and the mode of $1; check that stat is GNU stat" ;; + esac + if [ "$ce_owner" != 0 ] && [ "$ce_owner" != "$uid" ]; then + die "$1 is owned by user $ce_owner; it must be owned by $owners (fix it with chown, or use another path)" + fi + if [ "$((0$ce_mode & 022))" != 0 ]; then + if [ "$2" != shared ] || [ ! -d "$1" ] || [ "$((0$ce_mode & 01000))" = 0 ]; then + die "group or others can write to $1; only $owners may (fix it with chmod go-w, or use another path)" + fi + fi +} + +# check_tree checks the absolute path $1 as check_entry does, with $2, and +# each directory above it, up to /, as shared. $1 must have no link, . or +# .. in it (real_dir). +check_tree() { + ct_path=$1 + check_entry "$ct_path" "$2" + while [ "$ct_path" != / ]; do + ct_path=${ct_path%/*} + if [ -z "$ct_path" ]; then + ct_path=/ + fi + check_entry "$ct_path" shared + done +} + +# parse_args reads the arguments into want_version, bin_dir, gh and +# reinstall. +parse_args() { + while [ "$#" -gt 0 ]; do + case $1 in + --version) + if [ "$#" -lt 2 ]; then + usage_error "--version needs a version, such as 0.2.0" + fi + if ! is_version "$2"; then + usage_error "--version must be X.Y.Z, such as 0.2.0" + fi + want_version=$2 + shift 2 + ;; + --bin-dir) + if [ "$#" -lt 2 ]; then + usage_error "--bin-dir needs a directory" + fi + bin_dir=$2 + shift 2 + ;; + --gh) + if [ "$#" -lt 2 ]; then + usage_error "--gh needs the path of gh" + fi + gh=$2 + shift 2 + ;; + --reinstall) + reinstall=1 + shift + ;; + --help | -h) + usage + exit 0 + ;; + *) + usage_error "unknown argument: $1" + ;; + esac + done + case $bin_dir in + /*) ;; + *) usage_error "--bin-dir must be an absolute path" ;; + esac + case $gh in + '' | /*) ;; + *) usage_error "--gh must be an absolute path" ;; + esac +} + +# check_platform checks that this is Linux on amd64 or arm64. +check_platform() { + os=$(uname -s) || die "cannot run uname -s; check that $root_path has the program uname" + if [ "$os" != Linux ]; then + die "pullgate runs on Linux only, and this is $os; run this on a Linux host" + fi + machine=$(uname -m) || die "cannot run uname -m; check that $root_path has the program uname" + case $machine in + x86_64 | amd64) + arch=amd64 + gh_sha256=$gh_sha256_amd64 + ;; + aarch64 | arm64) + arch=arm64 + gh_sha256=$gh_sha256_arm64 + ;; + *) + die "pullgate has releases for amd64 and arm64 only, and this machine is $machine; build it from the source (README.md, section Install)" + ;; + esac +} + +# check_paths checks, before anything is downloaded, the places that the +# script runs programs from and writes to: the bin directory, the old +# file, and the gh of --gh. The script runs the old file and the gh, and +# as root it must not run a file that another user can change. A link as +# the old file or as the gh is refused: name the file itself. +check_paths() { + if [ ! -d "$bin_dir" ]; then + die "$bin_dir is not a directory; make it, or give another --bin-dir" + fi + real_dir "$bin_dir" + bin_dir=$real + check_tree "$bin_dir" own + if [ ! -w "$bin_dir" ]; then + die "cannot write to $bin_dir; run this as root" + fi + target=$bin_dir/pullgate + if [ -L "$target" ]; then + die "$target is a link; the script replaces only a file (remove the link, or give another --bin-dir)" + fi + if [ -e "$target" ]; then + if [ ! -f "$target" ]; then + die "$target is not a file; remove it, or give another --bin-dir" + fi + check_entry "$target" own + fi + if [ -n "$gh" ]; then + if [ -L "$gh" ] || [ ! -f "$gh" ] || [ ! -x "$gh" ]; then + die "--gh $gh is not a program file; name the file itself, not a link" + fi + gh_dir=${gh%/*} + real_dir "${gh_dir:-/}" + gh=${real%/}/${gh##*/} + check_tree "$gh" own + fi +} + +# make_tmp makes the private temporary directory in TMPDIR, or /tmp. +# TMPDIR, and each directory above it, must be safe as check_tree says: +# else another user could swap a checked file in it for another one. The +# new directory itself must have the owner and mode 0700 that mktemp +# gives. The trap of main removes it. +make_tmp() { + real_dir "${TMPDIR:-/tmp}" + tmp_parent=$real + check_tree "$tmp_parent" shared + tmp=$(mktemp -d "$tmp_parent/pullgate-install.XXXXXXXX") || + die "cannot make a temporary directory in $tmp_parent; set TMPDIR to a directory that only root can write, such as /root" + check_entry "$tmp" own + tmp_fix="set TMPDIR to a directory that only root can write and where programs can run, such as /root" + mkdir "$tmp/home" "$tmp/gh" "$tmp/new" || die "cannot make directories in $tmp; check the free space in $tmp_parent" +} + +# download gets the URL $1 into the file $2, at most $3 bytes: HTTPS only, +# also after a redirect, with TLS 1.2 or newer, with retries and a time +# limit. An HTTP error is a failure. -q comes first, so curl reads no +# .curlrc. +download() { + curl -q --proto '=https' --proto-redir '=https' --tlsv1.2 --fail --silent --show-error --location \ + --retry 3 --connect-timeout 30 --max-time 600 --max-filesize "$3" --output "$2" "$1" /dev/null) || installed_out= + installed=${installed_out#pullgate } + if [ "pullgate $installed" != "$installed_out" ] || ! is_version "$installed"; then + installed= + fi + fi + if [ -z "$installed" ]; then + if [ -z "$reinstall" ]; then + die "$target has an unknown version (a build from the source, or it does not run); to replace it with pullgate $version, run this again with --reinstall" + fi + say "$target has an unknown version. pullgate $version will replace it, as --reinstall asks." + return 0 + fi + compare_versions "$version" "$installed" + case $cmp in + 0) + if [ -z "$reinstall" ]; then + say "$target says that it is pullgate $version already. Nothing to do." + say "This did not check the installed file. To replace it with a checked copy, run this again with --reinstall." + exit 0 + fi + say "Installing pullgate $version again as $target, as --reinstall asks." + ;; + 1) + say "Updating $target from pullgate $installed to pullgate $version." + ;; + *) + if [ -z "$want_version" ]; then + say "$target says that it is pullgate $installed, which is newer than $version, the newest release. Nothing to do." + say "This did not check the installed file. To install $version anyway, run this again with --version $version." + exit 0 + fi + say "This is a downgrade: replacing pullgate $installed with the older pullgate $version, as --version asks." + ;; + esac +} + +# download_release gets the tarball for this machine, SHA256SUMS and the +# bundle of the build attestation. +download_release() { + tarball=pullgate_${version}_linux_${arch}.tar.gz + bundle=pullgate_${version}.sigstore.json + base=https://github.com/$repo/releases/download/v$version + say "Downloading $tarball, SHA256SUMS and $bundle." + download "$base/$tarball" "$tmp/$tarball" "$max_big" || die "cannot download $base/$tarball; check the network and try again" + download "$base/SHA256SUMS" "$tmp/SHA256SUMS" "$max_small" || die "cannot download $base/SHA256SUMS; check the network and try again" + download "$base/$bundle" "$tmp/$bundle" "$max_small" || die "cannot download $base/$bundle; check the network and try again" +} + +# check_sha256 checks the SHA-256 of the tarball against its own line in +# SHA256SUMS. There must be exactly one such line. It finds a broken +# download early. It proves nothing about who built the file: whoever can +# publish a release can publish its SHA256SUMS too. The attestation proves +# that. +check_sha256() { + want= + while read -r line_sum line_name || [ -n "$line_sum" ]; do + if [ "$line_name" = "$tarball" ] || [ "$line_name" = "*$tarball" ]; then + if [ -n "$want" ]; then + die "SHA256SUMS of the release has more than one line for $tarball; do not use this release, and report it at https://github.com/$repo/issues" + fi + want=$line_sum + fi + done <"$tmp/SHA256SUMS" + if [ -z "$want" ]; then + die "SHA256SUMS of the release has no line for $tarball; do not use this release, and report it at https://github.com/$repo/issues" + fi + sha256_of "$tmp/$tarball" + if [ "$file_sha256" != "$want" ]; then + die "the SHA-256 of $tarball is not the one in SHA256SUMS; the download is broken or changed, try again later" + fi +} + +# get_gh sets gh to the gh that checks the attestation: the one of --gh, +# which check_paths checked, or gh $gh_version, downloaded and checked +# against the SHA-256 in this script. It must be $gh_min_version or newer: +# the first line of gh --version must be "gh version X.Y.Z", then a space +# or nothing, so a version such as 2.93.0-rc.1 does not count. +get_gh() { + gh_hint=" (check that $gh runs here and is gh $gh_min_version or newer)" + if [ -z "$gh" ]; then + gh_hint=" (if programs cannot run in $tmp_parent, use --gh, or $tmp_fix)" + gh_tarball=gh_${gh_version}_linux_${arch}.tar.gz + say "Downloading gh $gh_version to check the attestation." + download "https://github.com/cli/cli/releases/download/v$gh_version/$gh_tarball" "$tmp/$gh_tarball" "$max_big" || + die "cannot download $gh_tarball; check the network, or give a gh with --gh" + sha256_of "$tmp/$gh_tarball" + if [ "$file_sha256" != "$gh_sha256" ]; then + die "the SHA-256 of $gh_tarball is not the one in this script; give a gh with --gh" + fi + tar --no-same-owner -xzf "$tmp/$gh_tarball" -C "$tmp/gh" "gh_${gh_version}_linux_${arch}/bin/gh" /dev/null || sync || die "cannot write $tmp_target to the disk; check the disk" + renaming=1 + mv -f "$tmp_target" "$target" || die "cannot rename the new file to $target; check that $bin_dir is not read-only" + tmp_target= + renamed=1 + sync -- "$bin_dir" 2>/dev/null || sync || : +} + +# print_restart prints what the new file says, and what to restart. It +# restarts nothing. +print_restart() { + if done_out=$(limited "$max_run" "$target" version >"$FAKE_LOGS/curl" +out= +max= +url= +while [ "$#" -gt 0 ]; do + case $1 in + --output) + out=$2 + shift + ;; + --max-filesize) + max=$2 + shift + ;; + esac + url=$1 + shift +done +case $url in +https://*) ;; +*) + echo "fake curl: not HTTPS: $url" >&2 + exit 1 + ;; +esac +file=$FAKE_WEB/${url#https://} +if [ ! -f "$file" ]; then + echo "curl: (22) The requested URL returned error: 404" >&2 + exit 22 +fi +if [ -n "$max" ] && [ "$(wc -c <"$file")" -gt "$max" ]; then + echo "curl: (63) Maximum file size exceeded" >&2 + exit 63 +fi +cp "$file" "$out" +` + +const fakeUname = `#!/bin/sh +# A fake uname: the system and the CPU of the test. +case $1 in +-s) echo "${FAKE_UNAME_S:-Linux}" ;; +-m) echo "${FAKE_UNAME_M:-x86_64}" ;; +*) exit 1 ;; +esac +` + +const fakeGh = `#!/bin/sh +# A fake gh. It writes down each call, one a line, its own path, and the +# environment of each kind of call. For --version, it prints the version +# $FAKE_GH_VERSION, or exits with $FAKE_GH_VERSION_EXIT. For attestation +# verify, it writes down its arguments, keeps a copy of the file and of the +# bundle to check, and exits with $FAKE_GH_EXIT. With $FAKE_GH_WAIT, it +# makes that file instead, and waits. +printf '%s\n' "$*" >>"$FAKE_LOGS/gh" +printf '%s\n' "$0" >"$FAKE_LOGS/gh-path" +env >"$FAKE_LOGS/gh-env-$1" +if [ "$1" = --version ]; then + if [ -n "${FAKE_GH_VERSION_EXIT:-}" ]; then + exit "$FAKE_GH_VERSION_EXIT" + fi + echo "gh version ${FAKE_GH_VERSION:-2.102.0} (2026-09-30)" + echo "https://github.com/cli/cli/releases/tag/v${FAKE_GH_VERSION:-2.102.0}" + exit 0 +fi +printf '%s\n' "$@" >"$FAKE_LOGS/gh-args" +cp "$3" "$FAKE_LOGS/gh-file" || exit 2 +cp "$5" "$FAKE_LOGS/gh-bundle" || exit 2 +if [ -n "${FAKE_GH_WAIT:-}" ]; then + : >"$FAKE_GH_WAIT" + exec sleep 60 +fi +exit "${FAKE_GH_EXIT:-0}" +` + +// fakePullgate returns a fake pullgate. "pullgate version" prints the +// lines. The note tells copies apart, such as the CPU of a tarball. Each +// run writes the note to $FAKE_LOGS/pullgate-runs, and the note and the +// directory of the file to $FAKE_LOGS/pullgate-dirs, so a test can see +// which copies ran, and where. +func fakePullgate(note string, lines ...string) []byte { + return fmt.Appendf(nil, "#!/bin/sh\n# A fake pullgate (%s).\necho '%s' >>\"$FAKE_LOGS/pullgate-runs\"\n"+ + "echo \"%s ${0%%/*}\" >>\"$FAKE_LOGS/pullgate-dirs\"\n"+ + "if [ \"$1\" = version ]; then\n\tprintf '%%s\\n' '%s'\nfi\n", + note, note, note, strings.Join(lines, "' '")) +} + +// failingPullgate is a fake pullgate that does not run. +var failingPullgate = []byte("#!/bin/sh\necho 'cannot run' >&2\nexit 1\n") + +// says returns the fake pullgate of each CPU of a release, for +// installer.release. +func says(lines ...string) func(arch string) []byte { + return func(arch string) []byte { return fakePullgate(arch, lines...) } +} + +// tarFile is a file in a tarball of tarGz. +type tarFile struct { + name string + mode int64 + data []byte +} + +// tarGz returns a tar.gz file with these files. +func tarGz(t *testing.T, files ...tarFile) []byte { + t.Helper() + var buf bytes.Buffer + gz := gzip.NewWriter(&buf) + tw := tar.NewWriter(gz) + for _, f := range files { + hdr := &tar.Header{Name: f.name, Mode: f.mode, Size: int64(len(f.data)), ModTime: time.Unix(1_760_000_000, 0)} + if err := tw.WriteHeader(hdr); err != nil { + t.Fatal(err) + } + if _, err := tw.Write(f.data); err != nil { + t.Fatal(err) + } + } + if err := tw.Close(); err != nil { + t.Fatal(err) + } + if err := gz.Close(); err != nil { + t.Fatal(err) + } + return buf.Bytes() +} + +// installer runs install.sh against fakes. +type installer struct { + t *testing.T + dir string // the working directory of the script + script string // the path of the script + web string // the files of the fake GitHub + bin string // the directory of --bin-dir + tmp string // TMPDIR of the script: it must be empty after each run + logs string // what the fake programs write down + fakes string // the fake curl and uname, first in PATH + gh string // the fake gh, for --gh + binArg string // the value of --bin-dir, if it is not bin + env []string // more environment for the script +} + +func newInstaller(t *testing.T) *installer { + t.Helper() + if os.Geteuid() == 0 { + skipOrFail(t, "as root, install.sh runs only the programs of the system, not the fakes of the test") + } + for _, name := range []string{"sed", "tar", "gzip", "sha256sum", "install", "mktemp", "id", "stat", "cp", "env", "wc", "sleep", "timeout", "sync"} { + if _, err := exec.LookPath(name); err != nil { + skipOrFail(t, "%s is not installed", name) + } + } + script, err := filepath.Abs("install.sh") + if err != nil { + t.Fatal(err) + } + // The script refuses a directory that group or others can write to. + // Under a umask such as 002, t.TempDir is one. + dir := privateDir(t) + in := &installer{ + t: t, + dir: dir, + script: script, + web: filepath.Join(dir, "web"), + bin: filepath.Join(dir, "bin"), + tmp: filepath.Join(dir, "tmp"), + logs: filepath.Join(dir, "logs"), + fakes: filepath.Join(dir, "fakes"), + gh: filepath.Join(dir, "gh"), + } + for _, d := range []string{in.web, in.bin, in.tmp, in.logs, in.fakes} { + mkdir(t, d, 0o700) + } + writeFile(t, filepath.Join(in.fakes, "curl"), []byte(fakeCurl), 0o700) + writeFile(t, filepath.Join(in.fakes, "uname"), []byte(fakeUname), 0o700) + writeFile(t, in.gh, []byte(fakeGh), 0o700) + if exec.CommandContext(t.Context(), filepath.Join(in.fakes, "uname"), "-s").Run() != nil { + skipOrFail(t, "a program in the temporary directory %s cannot run", dir) + } + return in +} + +// privateDir returns a new temporary directory with mode 0700, by its path +// without links: the script prints such paths. +func privateDir(t *testing.T) string { + t.Helper() + dir, err := filepath.EvalSymlinks(t.TempDir()) + if err != nil { + t.Fatal(err) + } + if err := os.Chmod(dir, 0o700); err != nil { + t.Fatal(err) + } + return dir +} + +// mkdir makes the directory path with exactly mode. +func mkdir(t *testing.T, path string, mode os.FileMode) { + t.Helper() + if err := os.Mkdir(path, 0o700); err != nil { + t.Fatal(err) + } + if err := os.Chmod(path, mode); err != nil { + t.Fatal(err) + } +} + +// releaseJSON is the answer of the fake GitHub API for a release, in the +// form of the real one. +func releaseJSON(tag string) []byte { + return fmt.Appendf(nil, "{\n \"url\": \"https://api.github.com/repos/code6x/pullgate/releases/1\",\n"+ + " \"tag_name\": %q,\n \"name\": %q,\n \"draft\": false\n}\n", tag, tag) +} + +// latest makes tag the newest release on the fake GitHub API. +func (in *installer) latest(tag string) { + in.serve(latestPath, releaseJSON(tag)) +} + +// release puts a release on the fake GitHub: its answer of the API, for +// each CPU a tarball with pullgate, LICENSE and README.md, and SHA256SUMS +// and the bundle. pullgate returns the file pullgate of each CPU. +func (in *installer) release(version string, pullgate func(arch string) []byte) { + in.serve(tagPath+version, releaseJSON("v"+version)) + var sums strings.Builder + for _, arch := range []string{"amd64", "arm64"} { + name := "pullgate_" + version + "_linux_" + arch + ".tar.gz" + data := tarGz(in.t, + tarFile{"pullgate", 0o755, pullgate(arch)}, + tarFile{"LICENSE", 0o644, []byte("a made-up license\n")}, + tarFile{"README.md", 0o644, []byte("# a made-up readme\n")}) + in.serve(releasePath+version+"/"+name, data) + fmt.Fprintf(&sums, "%x %s\n", sha256.Sum256(data), name) + } + in.serve(releasePath+version+"/SHA256SUMS", []byte(sums.String())) + in.serve(releasePath+version+"/pullgate_"+version+".sigstore.json", []byte(bundle(version))) +} + +// bundle is the made-up bundle of a release. +func bundle(version string) string { + return `{"mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json", "release": "` + version + `"}` + "\n" +} + +// ghRelease puts a tarball of gh 2.102.0 for amd64 on the fake GitHub, +// with the fake gh in it. It returns the SHA-256 of the tarball, in hex. +func (in *installer) ghRelease() string { + data := tarGz(in.t, + tarFile{"gh_2.102.0_linux_amd64/LICENSE", 0o644, []byte("a made-up license\n")}, + tarFile{"gh_2.102.0_linux_amd64/bin/gh", 0o755, []byte(fakeGh)}) + in.serve(ghPath+"2.102.0/gh_2.102.0_linux_amd64.tar.gz", data) + return fmt.Sprintf("%x", sha256.Sum256(data)) +} + +// serve puts a file at https://path on the fake GitHub. +func (in *installer) serve(path string, data []byte) { + in.t.Helper() + file := filepath.Join(in.web, filepath.FromSlash(path)) + if err := os.MkdirAll(filepath.Dir(file), 0o700); err != nil { + in.t.Fatal(err) + } + writeFile(in.t, file, data, 0o600) +} + +// unserve removes the file at https://path from the fake GitHub. +func (in *installer) unserve(path string) { + in.t.Helper() + if err := os.Remove(filepath.Join(in.web, filepath.FromSlash(path))); err != nil { + in.t.Fatal(err) + } +} + +// installed makes data the installed pullgate. +func (in *installer) installed(data []byte) { + writeFile(in.t, filepath.Join(in.bin, "pullgate"), data, 0o755) +} + +// result is the end of a run of the script. +type result struct { + code int + stdout, stderr string +} + +// run runs the script with the arguments. +func (in *installer) run(args ...string) result { + in.t.Helper() + return runCmd(in.t, in.command(args...)) +} + +// runCmd runs cmd, and returns its exit code and output. +func runCmd(t *testing.T, cmd *exec.Cmd) result { + t.Helper() + var stdout, stderr bytes.Buffer + cmd.Stdout, cmd.Stderr = &stdout, &stderr + err := cmd.Run() + var exit *exec.ExitError + if err != nil && !errors.As(err, &exit) { + t.Fatalf("cannot run %s: %v", cmd.Path, err) + } + return result{cmd.ProcessState.ExitCode(), stdout.String(), stderr.String()} +} + +// command returns the command that runs the script with --bin-dir of the +// test and then args, with stdin from /dev/null. A --bin-dir in args +// comes later, so it counts. +func (in *installer) command(args ...string) *exec.Cmd { + bin := in.bin + if in.binArg != "" { + bin = in.binArg + } + cmd := exec.CommandContext(in.t.Context(), "/bin/sh", append([]string{in.script, "--bin-dir", bin}, args...)...) + cmd.Dir = in.dir + cmd.Env = append([]string{ + "PATH=" + in.fakes + string(os.PathListSeparator) + os.Getenv("PATH"), + "HOME=" + in.dir, + "TMPDIR=" + in.tmp, + "FAKE_WEB=" + in.web, + "FAKE_LOGS=" + in.logs, + }, in.env...) + return cmd +} + +// files returns the mode and the content of each file in dir, by name: a +// link has its target, and a directory or another kind of file has only +// its mode. +func files(t *testing.T, dir string) map[string]string { + t.Helper() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + got := map[string]string{} + for _, e := range entries { + info, err := e.Info() + if err != nil { + t.Fatal(err) + } + path := filepath.Join(dir, e.Name()) + got[e.Name()] = info.Mode().String() + switch { + case info.Mode().IsRegular(): + got[e.Name()] += " " + string(readFile(t, path)) + case info.Mode()&fs.ModeSymlink != 0: + target, err := os.Readlink(path) + if err != nil { + t.Fatal(err) + } + got[e.Name()] += " -> " + target + } + } + return got +} + +// checkTmpGone checks that the temporary directory of the script is gone. +func (in *installer) checkTmpGone() { + in.t.Helper() + if left := files(in.t, in.tmp); len(left) != 0 { + in.t.Errorf("the temporary directory is still there: %v", slices.Sorted(maps.Keys(left))) + } +} + +// checkFailed checks a run that must fail with code and a last line that +// holds want, and that it changed nothing in the bin directory. +func (in *installer) checkFailed(r result, code int, want string, before map[string]string) { + in.t.Helper() + end := " (exit " + strconv.Itoa(code) + ")\n" + if code == 1 { + end = "; nothing was installed" + end + } + last := lastLine(r.stderr) + if r.code != code || !strings.HasPrefix(last, "pullgate: ") || !strings.Contains(last, want) || !strings.HasSuffix(last, end) { + in.t.Errorf("exit code %d, last line %q; want %d and a line with %q and %q\nstdout:\n%s\nstderr:\n%s", + r.code, last, code, want, end, r.stdout, r.stderr) + } + if after := files(in.t, in.bin); !maps.Equal(after, before) { + in.t.Errorf("the bin directory changed: %v, before %v", slices.Sorted(maps.Keys(after)), slices.Sorted(maps.Keys(before))) + } + in.checkTmpGone() +} + +// curlCalls returns the arguments of each call of curl. +func (in *installer) curlCalls() [][]string { + in.t.Helper() + var calls [][]string + for _, line := range in.log("curl") { + calls = append(calls, strings.Fields(line)) + } + return calls +} + +// urls returns the URL of each call of curl, in order. +func (in *installer) urls() []string { + in.t.Helper() + var urls []string + for _, call := range in.curlCalls() { + urls = append(urls, call[len(call)-1]) + } + return urls +} + +// log returns the lines that a fake wrote to the log name, or none. +func (in *installer) log(name string) []string { + in.t.Helper() + data, err := os.ReadFile(filepath.Join(in.logs, name)) + if errors.Is(err, fs.ErrNotExist) { + return nil + } + if err != nil { + in.t.Fatal(err) + } + return strings.Split(strings.TrimSuffix(string(data), "\n"), "\n") +} + +// ghChecked reports whether gh attestation verify ran. +func (in *installer) ghChecked() bool { + return in.log("gh-args") != nil +} + +// releaseURLs are the URLs of the files of a release, for amd64. +func releaseURLs(version string) []string { + base := "https://" + releasePath + version + "/" + return []string{base + "pullgate_" + version + "_linux_amd64.tar.gz", base + "SHA256SUMS", base + "pullgate_" + version + ".sigstore.json"} +} + +const latestURL = "https://" + latestPath + +// tagURL is the URL of the API for the release of version. +func tagURL(version string) string { return "https://" + tagPath + version } + +// TestInstall installs a release where no pullgate is, when every check +// passes, and checks how the script ran curl, gh and the new pullgate. +func TestInstall(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + // Tokens, a host and other places for the config of gh: none of them + // may reach gh. + token := "made-up-token-" + rand.Text() + for _, name := range tokenVars { + in.env = append(in.env, name+"="+token) + } + in.env = append(in.env, "GH_CONFIG_DIR=/nonexistent/gh", "XDG_CONFIG_HOME=/nonexistent/config", + "XDG_CACHE_HOME=/nonexistent/cache", "XDG_DATA_HOME=/nonexistent/data", "XDG_STATE_HOME=/nonexistent/state") + // Variables that change what the programs do: the script removes + // them. Through TAR_OPTIONS, tar would run a command. + ran := filepath.Join(in.dir, "tar-ran-a-command") + in.env = append(in.env, "TAR_OPTIONS=--checkpoint=1 --checkpoint-action=exec=touch "+ran, "LC_ALL=de_DE.UTF-8") + for _, name := range unsafeVars { + in.env = append(in.env, name+"=/nonexistent/made-up") + } + + r := in.run("--gh", in.gh) + if r.code != 0 { + t.Fatalf("exit code %d\nstdout:\n%s\nstderr:\n%s", r.code, r.stdout, r.stderr) + } + // Only pullgate of amd64 is in the bin directory, with mode 0755. + want := map[string]string{"pullgate": "-rwxr-xr-x " + string(fakePullgate("amd64", "pullgate 0.2.0"))} + if got := files(t, in.bin); !maps.Equal(got, want) { + t.Errorf("the bin directory holds %q, want %q", got, want) + } + in.checkTmpGone() + for _, s := range []string{"Installing pullgate 0.2.0 as " + in.bin + "/pullgate.", "version says: pullgate 0.2.0", + "This script restarts nothing.", "systemctl restart pullgate-listen.service", "pullgate-run@NAME.timer", + "pullgate-apply@NAME.path"} { + if !strings.Contains(r.stdout, s) { + t.Errorf("stdout does not say %q:\n%s", s, r.stdout) + } + } + if _, err := os.Lstat(ran); err == nil { + t.Error("tar ran the command of TAR_OPTIONS") + } + + // curl: the newest release, then the files of the release, each with + // no .curlrc, over HTTPS only, with TLS 1.2 or newer, failing on an + // HTTP error, with retries, a time limit and a size limit. + wantURLs := append([]string{latestURL}, releaseURLs("0.2.0")...) + if got := in.urls(); !slices.Equal(got, wantURLs) { + t.Errorf("curl got the URLs\n%q\nwant\n%q", got, wantURLs) + } + for i, call := range in.curlCalls() { + if call[0] != "-q" { + t.Errorf("a call of curl does not start with -q, so curl reads .curlrc: %q", call) + } + limit := maxSmall + if strings.HasSuffix(call[len(call)-1], ".tar.gz") { + limit = maxBig + } + for _, want := range [][]string{{"--proto", "=https"}, {"--proto-redir", "=https"}, {"--tlsv1.2"}, {"--fail"}, + {"--retry", "3"}, {"--max-time", "600"}, {"--max-filesize", limit}} { + if !slices.ContainsFunc(windows(call, len(want)), func(w []string) bool { return slices.Equal(w, want) }) { + t.Errorf("call %d of curl has no %q: %q", i, want, call) + } + } + } + + // gh: its version, then the check with the identity of + // docs/releasing.md, of the file that the script downloaded. + if got, want := in.log("gh"), []string{"--version", "attestation verify"}; len(got) != 2 || got[0] != want[0] || !strings.HasPrefix(got[1], want[1]) { + t.Fatalf("calls of gh: %q, want --version and then attestation verify", got) + } + args := in.log("gh-args") + if len(args) < 3 { + t.Fatalf("gh got %q", args) + } + tmp := filepath.Dir(args[2]) // the temporary directory of the script + if filepath.Dir(tmp) != in.tmp || !strings.HasPrefix(filepath.Base(tmp), "pullgate-install.") { + t.Errorf("gh checked %s, not a file in a new directory in TMPDIR %s", args[2], in.tmp) + } + wantArgs := []string{"attestation", "verify", filepath.Join(tmp, "pullgate_0.2.0_linux_amd64.tar.gz"), + "--bundle", filepath.Join(tmp, "pullgate_0.2.0.sigstore.json"), + "--repo", "code6x/pullgate", "--cert-identity", certIdentity, "--deny-self-hosted-runners"} + if !slices.Equal(args, wantArgs) { + t.Errorf("gh got the arguments\n%q\nwant\n%q", args, wantArgs) + } + served := readFile(t, filepath.Join(in.web, releasePath+"0.2.0", "pullgate_0.2.0_linux_amd64.tar.gz")) + if checked := readFile(t, filepath.Join(in.logs, "gh-file")); !bytes.Equal(checked, served) { + t.Error("gh checked another file than the tarball of the release") + } + if checked := readFile(t, filepath.Join(in.logs, "gh-bundle")); string(checked) != bundle("0.2.0") { + t.Errorf("gh checked with the bundle %q, want %q", checked, bundle("0.2.0")) + } + + // The new pullgate ran first from the temporary directory, then as the + // new file in the bin directory before the rename, and then as the + // installed file. + wantDirs := []string{"amd64 " + filepath.Join(tmp, "new"), "amd64 " + in.bin, "amd64 " + in.bin} + if got := in.log("pullgate-dirs"); !slices.Equal(got, wantDirs) { + t.Errorf("the new pullgate ran in\n%q\nwant\n%q", got, wantDirs) + } + + // The environment of gh, for both calls: no token and no host, its + // home, config and XDG directories in the temporary directory, no + // update notices, prompts or telemetry, LC_ALL=C, and none of the + // unsafe variables. + for _, call := range []string{"--version", "attestation"} { + env := readEnv(t, filepath.Join(in.logs, "gh-env-"+call)) + for _, name := range append(slices.Clone(tokenVars), append([]string{"TAR_OPTIONS"}, unsafeVars...)...) { + if v, ok := env[name]; ok { + t.Errorf("gh %s got %s (%d bytes)", call, name, len(v)) + } + } + for name, value := range env { + if strings.Contains(value, token) { + t.Errorf("gh %s got the token in %s", call, name) + } + } + if env["HOME"] != filepath.Join(tmp, "home") { + t.Errorf("gh %s got HOME=%q, want %q", call, env["HOME"], filepath.Join(tmp, "home")) + } + for _, name := range []string{"GH_CONFIG_DIR", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"} { + if !strings.HasPrefix(env[name], tmp+"/") { + t.Errorf("gh %s got %s=%q, want a directory in %s", call, name, env[name], tmp) + } + } + for name, want := range map[string]string{"GH_NO_UPDATE_NOTIFIER": "1", "GH_NO_EXTENSION_UPDATE_NOTIFIER": "1", + "GH_PROMPT_DISABLED": "1", "GH_TELEMETRY": "false", "LC_ALL": "C"} { + if env[name] != want { + t.Errorf("gh %s got %s=%q, want %q", call, name, env[name], want) + } + } + } +} + +// TestInstallReplaces replaces an installed pullgate: an older version, +// one whose version is not known with --reinstall, the same one with +// --reinstall, and with --version an older one (a downgrade). It also +// installs with paths that the script takes as safe. +func TestInstallReplaces(t *testing.T) { + all := append([]string{latestURL}, releaseURLs("0.2.0")...) + for _, tt := range []struct { + name string + installed []byte // the pullgate that is installed before + setup func(in *installer) // more changes before the run + args []string // after --gh + arch string // the CPU of the tarball that must be installed + say string // a part of stdout + urls []string // what curl gets + }{ + {name: "an older version", installed: fakePullgate("installed", "pullgate 0.1.0"), arch: "amd64", + say: "Updating BIN/pullgate from pullgate 0.1.0 to pullgate 0.2.0.", urls: all}, + {name: "a build from the source, with --reinstall", installed: fakePullgate("installed", "pullgate dev"), + args: []string{"--reinstall"}, arch: "amd64", + say: "BIN/pullgate has an unknown version. pullgate 0.2.0 will replace it, as --reinstall asks.", urls: all}, + {name: "a file that prints nothing, with --reinstall", installed: []byte("#!/bin/sh\n"), + args: []string{"--reinstall"}, arch: "amd64", say: "has an unknown version", urls: all}, + {name: "a file that does not run, with --reinstall", installed: failingPullgate, + args: []string{"--reinstall"}, arch: "amd64", say: "has an unknown version", urls: all}, + {name: "the same version, with --reinstall", installed: fakePullgate("installed", "pullgate 0.2.0"), + args: []string{"--reinstall"}, arch: "amd64", + say: "Installing pullgate 0.2.0 again as BIN/pullgate, as --reinstall asks.", urls: all}, + {name: "a downgrade, with --version", installed: fakePullgate("installed", "pullgate 0.3.0"), + args: []string{"--version", "0.2.0"}, arch: "amd64", + say: "This is a downgrade: replacing pullgate 0.3.0 with the older pullgate 0.2.0, as --version asks.", + urls: append([]string{tagURL("0.2.0")}, releaseURLs("0.2.0")...)}, + {name: "on arm64", setup: env("FAKE_UNAME_M=aarch64"), arch: "arm64", say: "Installing pullgate 0.2.0", + urls: []string{latestURL, "https://" + releasePath + "0.2.0/pullgate_0.2.0_linux_arm64.tar.gz", + "https://" + releasePath + "0.2.0/SHA256SUMS", "https://" + releasePath + "0.2.0/pullgate_0.2.0.sigstore.json"}}, + {name: "on amd64, when uname -m says amd64", setup: env("FAKE_UNAME_M=amd64"), arch: "amd64", + say: "Installing pullgate 0.2.0", urls: all}, + {name: "with gh 2.93.0, the oldest that counts", setup: env("FAKE_GH_VERSION=2.93.0"), arch: "amd64", + say: "with gh 2.93.0.", urls: all}, + // A directory with the sticky bit, as /tmp, may let others write. + {name: "a TMPDIR with the sticky bit", setup: func(in *installer) { + in.tmp = filepath.Join(in.dir, "shared-tmp") + mkdir(in.t, in.tmp, 0o777|os.ModeSticky) + }, arch: "amd64", say: "Installing pullgate 0.2.0", urls: all}, + {name: "a bin directory in a directory with the sticky bit", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "shared"), 0o777|os.ModeSticky) + in.bin = filepath.Join(in.dir, "shared", "bin") + mkdir(in.t, in.bin, 0o755) + }, arch: "amd64", say: "Installing pullgate 0.2.0", urls: all}, + // A link in the path of the bin directory is followed once, and the + // script uses the real path from then on. + {name: "a bin directory behind a link", setup: func(in *installer) { + in.binArg = filepath.Join(in.dir, "bin-link") + if err := os.Symlink(in.bin, in.binArg); err != nil { + in.t.Fatal(err) + } + }, arch: "amd64", say: "Installing pullgate 0.2.0 as BIN/pullgate.", urls: all}, + } { + t.Run(tt.name, func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + if tt.installed != nil { + in.installed(tt.installed) + } + if tt.setup != nil { + tt.setup(in) + } + r := in.run(append([]string{"--gh", in.gh}, tt.args...)...) + if r.code != 0 { + t.Fatalf("exit code %d\nstdout:\n%s\nstderr:\n%s", r.code, r.stdout, r.stderr) + } + want := map[string]string{"pullgate": "-rwxr-xr-x " + string(fakePullgate(tt.arch, "pullgate 0.2.0"))} + if got := files(t, in.bin); !maps.Equal(got, want) { + t.Errorf("the bin directory holds %q, want %q", got, want) + } + if say := strings.ReplaceAll(tt.say, "BIN", in.bin); !strings.Contains(r.stdout, say) { + t.Errorf("stdout does not say %q:\n%s", say, r.stdout) + } + if got := in.urls(); !slices.Equal(got, tt.urls) { + t.Errorf("curl got the URLs\n%q\nwant\n%q", got, tt.urls) + } + in.checkTmpGone() + }) + } +} + +// TestInstallNothingToDo: the version is installed already, or the +// installed one is newer and --version does not ask for the older one. +// The script exits with 0, downloads no file of the release and changes +// nothing. It says that it did not check the installed file. +func TestInstallNothingToDo(t *testing.T) { + for _, tt := range []struct { + name string + installed string + args []string + say string + urls []string + }{ + {"same version, the newest release", "0.2.0", nil, "BIN/pullgate says that it is pullgate 0.2.0 already. Nothing to do.\n" + + "This did not check the installed file. To replace it with a checked copy, run this again with --reinstall.", + []string{latestURL}}, + {"same version, with --version", "0.2.0", []string{"--version", "0.2.0"}, "says that it is pullgate 0.2.0 already", + []string{tagURL("0.2.0")}}, + {"a newer version", "0.3.0", nil, + "BIN/pullgate says that it is pullgate 0.3.0, which is newer than 0.2.0, the newest release. Nothing to do.\n" + + "This did not check the installed file. To install 0.2.0 anyway, run this again with --version 0.2.0.", + []string{latestURL}}, + {"a newer version in the second number", "0.10.0", nil, "which is newer than 0.2.0", []string{latestURL}}, + {"a newer version in the first number", "1.0.0", nil, "which is newer than 0.2.0", []string{latestURL}}, + {"a newer version, with --reinstall", "0.3.0", []string{"--reinstall"}, "which is newer than 0.2.0", []string{latestURL}}, + } { + t.Run(tt.name, func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate "+tt.installed)) + before := files(t, in.bin) + r := in.run(append([]string{"--gh", in.gh}, tt.args...)...) + if r.code != 0 || r.stderr != "" { + t.Errorf("exit code %d, stderr %q; want 0 and nothing", r.code, r.stderr) + } + if say := strings.ReplaceAll(tt.say, "BIN", in.bin); !strings.Contains(r.stdout, say) { + t.Errorf("stdout does not say %q:\n%s", say, r.stdout) + } + if got := in.urls(); !slices.Equal(got, tt.urls) { + t.Errorf("curl got the URLs %q, want %q", got, tt.urls) + } + if in.ghChecked() { + t.Error("gh checked an attestation") + } + if after := files(t, in.bin); !maps.Equal(after, before) { + t.Errorf("the bin directory changed") + } + in.checkTmpGone() + }) + } +} + +// TestInstallDenies: each failed check stops the script with exit code 1 +// and a last line that says why and that nothing was installed. The old +// pullgate stays, and no new file is left next to it. +func TestInstallDenies(t *testing.T) { + const tarball = "pullgate_0.2.0_linux_amd64.tar.gz" + sums := func(lines ...string) func(in *installer) { + return func(in *installer) { + in.serve(releasePath+"0.2.0/SHA256SUMS", []byte(strings.Join(lines, ""))) + } + } + sumOf := func(in *installer, arch string) string { + data := readFile(in.t, filepath.Join(in.web, releasePath+"0.2.0", "pullgate_0.2.0_linux_"+arch+".tar.gz")) + return fmt.Sprintf("%x", sha256.Sum256(data)) + } + for _, tt := range []struct { + name string + installed []byte // the installed pullgate; nil: pullgate 0.1.0 + setup func(in *installer) // after the newest release 0.2.0 is on the fake GitHub + args []string // nil: --gh with the fake gh + want string // a part of the last line + checked bool // whether gh attestation verify ran + noCurl bool // whether the script must stop before any download + noRun bool // whether the script must run no pullgate and no gh + }{ + // The platform. + {name: "platform not supported", setup: env("FAKE_UNAME_S=Darwin"), noCurl: true, + want: "pullgate runs on Linux only, and this is Darwin"}, + {name: "cpu not supported", setup: env("FAKE_UNAME_M=riscv64"), noCurl: true, + want: "amd64 and arm64 only, and this machine is riscv64"}, + {name: "cpu armv7 not supported", setup: env("FAKE_UNAME_M=armv7l"), noCurl: true, + want: "amd64 and arm64 only, and this machine is armv7l"}, + + // The paths that the script runs programs from and writes to. + {name: "no bin directory", args: []string{"--bin-dir", "/nonexistent/bin"}, noCurl: true, noRun: true, + want: "/nonexistent/bin is not a directory"}, + {name: "bin directory not writable", setup: func(in *installer) { chmod(in.t, in.bin, 0o500) }, + noCurl: true, noRun: true, want: "cannot write to BIN; run this as root"}, + {name: "bin directory writable by others", setup: func(in *installer) { chmod(in.t, in.bin, 0o777) }, + noCurl: true, noRun: true, want: "group or others can write to BIN; only root or user"}, + {name: "bin directory writable by group", setup: func(in *installer) { chmod(in.t, in.bin, 0o770) }, + noCurl: true, noRun: true, want: "group or others can write to BIN;"}, + {name: "bin directory with the sticky bit", setup: func(in *installer) { chmod(in.t, in.bin, 0o777|os.ModeSticky) }, + noCurl: true, noRun: true, want: "group or others can write to BIN;"}, + {name: "bin directory in a directory writable by others", setup: func(in *installer) { + open := filepath.Join(in.dir, "open") + mkdir(in.t, open, 0o777) + in.bin = filepath.Join(open, "bin") + mkdir(in.t, in.bin, 0o700) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open;"}, + {name: "target writable by others", setup: func(in *installer) { chmod(in.t, filepath.Join(in.bin, "pullgate"), 0o777) }, + noCurl: true, noRun: true, want: "group or others can write to BIN/pullgate;"}, + {name: "target is a symlink", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "elsewhere"), 0o700) + writeFile(in.t, filepath.Join(in.dir, "elsewhere", "pullgate"), fakePullgate("elsewhere", "pullgate 0.1.0"), 0o755) + replace(in.t, filepath.Join(in.bin, "pullgate"), func(path string) error { + return os.Symlink(filepath.Join(in.dir, "elsewhere", "pullgate"), path) + }) + }, noCurl: true, noRun: true, want: "BIN/pullgate is a link; the script replaces only a file"}, + {name: "target is a directory", setup: func(in *installer) { + replace(in.t, filepath.Join(in.bin, "pullgate"), func(path string) error { return os.Mkdir(path, 0o700) }) + }, noCurl: true, noRun: true, want: "BIN/pullgate is not a file"}, + {name: "target is a pipe", setup: func(in *installer) { + replace(in.t, filepath.Join(in.bin, "pullgate"), func(path string) error { return syscall.Mkfifo(path, 0o600) }) + }, noCurl: true, noRun: true, want: "BIN/pullgate is not a file"}, + {name: "TMPDIR writable by others", setup: func(in *installer) { + in.tmp = filepath.Join(in.dir, "open-tmp") + mkdir(in.t, in.tmp, 0o777) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open-tmp;"}, + {name: "TMPDIR in a directory writable by others", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "open"), 0o777) + in.tmp = filepath.Join(in.dir, "open", "tmp") + mkdir(in.t, in.tmp, 0o700) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open;"}, + {name: "no TMPDIR", setup: env("TMPDIR=/nonexistent/tmp"), noCurl: true, noRun: true, + want: "cannot find the directory /nonexistent/tmp"}, + {name: "gh writable by others", setup: func(in *installer) { chmod(in.t, in.gh, 0o777) }, + noCurl: true, noRun: true, want: "group or others can write to DIR/gh;"}, + {name: "gh in a directory writable by others", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "open"), 0o777) + in.gh = filepath.Join(in.dir, "open", "gh") + writeFile(in.t, in.gh, []byte(fakeGh), 0o700) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open;"}, + {name: "gh is a symlink", setup: func(in *installer) { + link := filepath.Join(in.dir, "gh-link") + if err := os.Symlink(in.gh, link); err != nil { + in.t.Fatal(err) + } + in.gh = link + }, noCurl: true, noRun: true, want: "--gh DIR/gh-link is not a program file; name the file itself, not a link"}, + {name: "gh missing", args: []string{"--gh", "/nonexistent/gh"}, noCurl: true, noRun: true, + want: "--gh /nonexistent/gh is not a program file"}, + {name: "gh not a program", setup: func(in *installer) { chmod(in.t, in.gh, 0o600) }, + noCurl: true, noRun: true, want: "--gh DIR/gh is not a program file"}, + + // The installed version. + {name: "installed version unknown", installed: fakePullgate("installed", "pullgate dev"), + want: "BIN/pullgate has an unknown version (a build from the source, or it does not run); " + + "to replace it with pullgate 0.2.0, run this again with --reinstall"}, + {name: "installed version prints nothing", installed: []byte("#!/bin/sh\n"), want: "has an unknown version"}, + {name: "installed file does not run", installed: failingPullgate, want: "has an unknown version"}, + + // The release and its files. + {name: "no answer from the API", setup: func(in *installer) { in.unserve(latestPath) }, + want: "cannot ask GitHub for the newest release"}, + {name: "API answer too big", setup: func(in *installer) { + in.serve(latestPath, bytes.Repeat([]byte(" "), 1<<20+1)) + }, want: "cannot ask GitHub for the newest release"}, + {name: "no release for --version", args: []string{"--version", "0.9.0"}, + want: "cannot get the release v0.9.0 from GitHub"}, + {name: "release tag does not match --version", setup: func(in *installer) { + in.serve(tagPath+"0.2.0", releaseJSON("v0.2.1")) + }, args: []string{"--version", "0.2.0"}, want: "GitHub names the release v0.2.0 as v0.2.1"}, + {name: "tag without v", setup: latest("0.2.0"), want: "GitHub does not name the release in the form vX.Y.Z"}, + {name: "tag with two numbers", setup: latest("v0.2"), want: "in the form vX.Y.Z"}, + {name: "tag with four numbers", setup: latest("v0.2.0.1"), want: "in the form vX.Y.Z"}, + {name: "tag with a leading zero", setup: latest("v0.02.0"), want: "in the form vX.Y.Z"}, + {name: "tag of a pre-release", setup: latest("v0.2.0-rc.1"), want: "in the form vX.Y.Z"}, + {name: "tag with a long number", setup: latest("v0.2.1234567890"), want: "in the form vX.Y.Z"}, + {name: "tag with a space", setup: latest("v0.2.0 "), want: "in the form vX.Y.Z"}, + {name: "two tags", setup: func(in *installer) { + in.serve(latestPath, []byte("{\n \"tag_name\": \"v0.2.0\",\n \"tag_name\": \"v0.3.0\"\n}\n")) + }, want: "in the form vX.Y.Z"}, + {name: "no tag", setup: func(in *installer) { + in.serve(latestPath, []byte("{\n \"name\": \"v0.2.0\"\n}\n")) + }, want: "in the form vX.Y.Z"}, + {name: "no tarball", setup: func(in *installer) { in.unserve(releasePath + "0.2.0/" + tarball) }, + want: "cannot download https://" + releasePath + "0.2.0/" + tarball}, + {name: "no SHA256SUMS", setup: func(in *installer) { in.unserve(releasePath + "0.2.0/SHA256SUMS") }, + want: "cannot download https://" + releasePath + "0.2.0/SHA256SUMS"}, + {name: "SHA256SUMS too big", setup: func(in *installer) { + sums(sumOf(in, "amd64")+" "+tarball+"\n", strings.Repeat("#", 1<<20))(in) + }, want: "cannot download https://" + releasePath + "0.2.0/SHA256SUMS"}, + {name: "no bundle", setup: func(in *installer) { in.unserve(releasePath + "0.2.0/pullgate_0.2.0.sigstore.json") }, + want: "cannot download https://" + releasePath + "0.2.0/pullgate_0.2.0.sigstore.json"}, + {name: "wrong sha256", setup: func(in *installer) { + sums(sumOf(in, "arm64")+" "+tarball+"\n", sumOf(in, "arm64")+" pullgate_0.2.0_linux_arm64.tar.gz\n")(in) + }, want: "the SHA-256 of " + tarball + " is not the one in SHA256SUMS"}, + {name: "SHA256SUMS has no line for the tarball", setup: func(in *installer) { + sums(sumOf(in, "arm64") + " pullgate_0.2.0_linux_arm64.tar.gz\n")(in) + }, want: "SHA256SUMS of the release has no line for " + tarball}, + {name: "SHA256SUMS has a line for a longer name only", setup: func(in *installer) { + sums(sumOf(in, "amd64") + " " + tarball + ".old\n")(in) + }, want: "SHA256SUMS of the release has no line for " + tarball}, + {name: "SHA256SUMS has two lines for the tarball", setup: func(in *installer) { + sums(sumOf(in, "amd64")+" "+tarball+"\n", sumOf(in, "amd64")+" *"+tarball+"\n")(in) + }, want: "SHA256SUMS of the release has more than one line for " + tarball}, + + // gh and the attestation. + {name: "attestation fails", setup: env("FAKE_GH_EXIT=1"), checked: true, + want: "gh attestation verify failed or ran longer than 300 seconds, so it is not proven that the release workflow built " + tarball + "; read the output of gh above"}, + {name: "gh too old", setup: env("FAKE_GH_VERSION=2.92.0"), want: " is gh 2.92.0; it must be gh 2.93.0 or newer"}, + {name: "gh pre-release", setup: env("FAKE_GH_VERSION=2.93.0-rc.1"), want: "cannot tell the version of "}, + {name: "gh version with more", setup: env("FAKE_GH_VERSION=2.102.0+ds1"), want: "cannot tell the version of "}, + {name: "gh with no version", setup: env("FAKE_GH_VERSION=DEV"), want: "cannot tell the version of "}, + {name: "gh --version fails", setup: env("FAKE_GH_VERSION_EXIT=1"), want: "/gh --version (check that "}, + {name: "downloaded gh with another sha256", setup: func(in *installer) { in.ghRelease() }, args: []string{}, + want: "the SHA-256 of gh_2.102.0_linux_amd64.tar.gz is not the one in this script"}, + {name: "no gh to download", args: []string{}, want: "cannot download gh_2.102.0_linux_amd64.tar.gz"}, + + // The new pullgate. The attestation proves which workflow built a + // file, not which version it is. A release 0.3.0 with an attested + // build of 0.2.0 passes the checksum and the attestation, and must + // still fail. + {name: "binary reports another version", setup: rel(says("pullgate 0.1.0")), checked: true, + want: "the new pullgate does not say that it is pullgate 0.2.0"}, + {name: "attested older build under a newer name", setup: func(in *installer) { + in.latest("v0.3.0") + in.release("0.3.0", says("pullgate 0.2.0")) + }, checked: true, want: "the new pullgate does not say that it is pullgate 0.3.0"}, + {name: "binary prints more than its version", setup: rel(says("pullgate 0.2.0", "pullgate 0.3.0")), checked: true, + want: "the new pullgate does not say that it is pullgate 0.2.0"}, + {name: "binary prints a v", setup: rel(says("pullgate v0.2.0")), checked: true, + want: "the new pullgate does not say that it is pullgate 0.2.0"}, + {name: "binary does not run", setup: rel(func(string) []byte { return failingPullgate }), checked: true, + want: "the new pullgate does not run, or runs longer than 60 seconds (if programs cannot run in "}, + {name: "tarball without pullgate", setup: func(in *installer) { + data := tarGz(in.t, tarFile{"LICENSE", 0o644, []byte("a made-up license\n")}) + in.serve(releasePath+"0.2.0/"+tarball, data) + sums(fmt.Sprintf("%x %s\n", sha256.Sum256(data), tarball))(in) + }, checked: true, want: "cannot take pullgate out of " + tarball}, + } { + t.Run(tt.name, func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + installed := tt.installed + if installed == nil { + installed = fakePullgate("installed", "pullgate 0.1.0") + } + in.installed(installed) + if tt.setup != nil { + tt.setup(in) + } + args := tt.args + if args == nil { + args = []string{"--gh", in.gh} + } else if len(args) > 0 && args[0] == "--version" { + args = append([]string{"--gh", in.gh}, args...) + } + before := files(t, in.bin) + r := in.run(args...) + want := strings.NewReplacer("BIN", in.bin, "DIR", in.dir).Replace(tt.want) + in.checkFailed(r, 1, want, before) + if in.ghChecked() != tt.checked { + t.Errorf("gh attestation verify ran: %v, want %v", in.ghChecked(), tt.checked) + } + if urls := in.urls(); tt.noCurl && len(urls) != 0 { + t.Errorf("curl got %q, want no call", urls) + } + if runs := append(in.log("pullgate-runs"), in.log("gh")...); tt.noRun && len(runs) != 0 { + t.Errorf("the script ran a pullgate or a gh: %q", runs) + } + // The new pullgate runs only after the attestation passed. + if ranNew := slices.ContainsFunc(in.log("pullgate-runs"), func(s string) bool { return s == "amd64" }); ranNew && !tt.checked { + t.Error("the new pullgate ran, but the attestation was not checked") + } + }) + } +} + +// TestInstallRunsNoNewFileBeforeTheCheck: when the attestation fails, the +// new pullgate never runs, not even for its version. +func TestInstallRunsNoNewFileBeforeTheCheck(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + in.env = append(in.env, "FAKE_GH_EXIT=1") + before := files(t, in.bin) + r := in.run("--gh", in.gh) + in.checkFailed(r, 1, "gh attestation verify failed", before) + // Only the installed pullgate ran, for its version. + if runs := in.log("pullgate-runs"); !slices.Equal(runs, []string{"installed"}) { + t.Errorf("these copies of pullgate ran: %q, want only the installed one", runs) + } +} + +// env returns a setup that adds the variables to the environment of the +// script. +func env(vars ...string) func(in *installer) { + return func(in *installer) { in.env = append(in.env, vars...) } +} + +// latest returns a setup that makes tag the newest release. +func latest(tag string) func(in *installer) { + return func(in *installer) { in.latest(tag) } +} + +// rel returns a setup that makes the release 0.2.0 again, with these +// files pullgate. +func rel(pullgate func(arch string) []byte) func(in *installer) { + return func(in *installer) { in.release("0.2.0", pullgate) } +} + +// chmod sets the mode of path, and sets it back to 0700 at the end of the +// test, so that the temporary directory can be removed. +func chmod(t *testing.T, path string, mode os.FileMode) { + t.Helper() + if err := os.Chmod(path, mode); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(path, 0o700) }) +} + +// replace removes the file path and makes something else there with +// create. +func replace(t *testing.T, path string, create func(path string) error) { + t.Helper() + if err := os.Remove(path); err != nil { + t.Fatal(err) + } + if err := create(path); err != nil { + t.Fatal(err) + } +} + +// TestInstallUsage: wrong arguments stop the script with exit code 64, +// before it downloads anything. +func TestInstallUsage(t *testing.T) { + for _, tt := range []struct { + args []string + want string + }{ + {[]string{"--bogus"}, "unknown argument: --bogus"}, + {[]string{"0.2.0"}, "unknown argument: 0.2.0"}, + {[]string{"--version=0.2.0"}, "unknown argument: --version=0.2.0"}, + {[]string{"--reinstall=yes"}, "unknown argument: --reinstall=yes"}, + {[]string{"--version"}, "--version needs a version, such as 0.2.0"}, + {[]string{"--version", "0.2"}, "--version must be X.Y.Z, such as 0.2.0"}, + {[]string{"--version", "v0.2.0"}, "--version must be X.Y.Z"}, + {[]string{"--version", "0.2.0.1"}, "--version must be X.Y.Z"}, + {[]string{"--version", "0.2.0-rc.1"}, "--version must be X.Y.Z"}, + {[]string{"--version", "00.2.0"}, "--version must be X.Y.Z"}, + {[]string{"--version", "0.-2.0"}, "--version must be X.Y.Z"}, + {[]string{"--version", ""}, "--version must be X.Y.Z"}, + {[]string{"--version", "--bin-dir"}, "--version must be X.Y.Z"}, + {[]string{"--bin-dir"}, "--bin-dir needs a directory"}, + {[]string{"--bin-dir", "bin"}, "--bin-dir must be an absolute path"}, + {[]string{"--gh"}, "--gh needs the path of gh"}, + {[]string{"--gh", "gh"}, "--gh must be an absolute path"}, + } { + t.Run(strings.Join(tt.args, " "), func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + before := files(t, in.bin) + r := in.run(tt.args...) + in.checkFailed(r, 64, tt.want, before) + if !strings.HasPrefix(r.stderr, "Usage: sh install.sh ") || r.stdout != "" { + t.Errorf("stdout %q, stderr %q; want the usage on stderr", r.stdout, r.stderr) + } + if urls := in.urls(); len(urls) != 0 { + t.Errorf("curl got %q", urls) + } + }) + } + for _, help := range []string{"--help", "-h"} { + in := newInstaller(t) + r := in.run(help) + if r.code != 0 || !strings.HasPrefix(r.stdout, "Usage: sh install.sh ") || !strings.Contains(r.stdout, "--reinstall") || r.stderr != "" { + t.Errorf("%s: exit code %d, stdout %q, stderr %q; want 0 and the usage on stdout", help, r.code, r.stdout, r.stderr) + } + } +} + +// TestInstallDownloadsGh runs a copy of the script whose SHA-256 of gh is +// the one of a fake gh: the script downloads the tarball of gh, checks it, +// takes gh out of it and checks the attestation with it. +func TestInstallDownloadsGh(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + sum := in.ghRelease() + script := string(readFile(t, in.script)) + pin := regexp.MustCompile(`(?m)^gh_sha256_amd64=[0-9a-f]{64}$`) + if n := len(pin.FindAllString(script, -1)); n != 1 { + t.Fatalf("install.sh has %d lines gh_sha256_amd64=, want 1", n) + } + in.script = filepath.Join(in.dir, "install-with-fake-gh.sh") + writeFile(t, in.script, []byte(pin.ReplaceAllString(script, "gh_sha256_amd64="+sum)), 0o600) + + r := in.run() + if r.code != 0 { + t.Fatalf("exit code %d\nstdout:\n%s\nstderr:\n%s", r.code, r.stdout, r.stderr) + } + want := append([]string{latestURL}, releaseURLs("0.2.0")...) + want = append(want, "https://"+ghPath+"2.102.0/gh_2.102.0_linux_amd64.tar.gz") + if got := in.urls(); !slices.Equal(got, want) { + t.Errorf("curl got the URLs\n%q\nwant\n%q", got, want) + } + if last := in.curlCalls()[len(want)-1]; !slices.Contains(last, maxBig) { + t.Errorf("the download of gh has no size limit %s: %q", maxBig, last) + } + // The gh that ran is the one from the tarball, in the temporary + // directory. + args := in.log("gh-args") + if !in.ghChecked() || len(args) < 3 { + t.Fatalf("gh attestation verify did not run: %q", args) + } + tmp := filepath.Dir(args[2]) + if got, want := in.log("gh-path"), filepath.Join(tmp, "gh", "gh_2.102.0_linux_amd64", "bin", "gh"); len(got) != 1 || got[0] != want { + t.Errorf("the gh that ran is %q, want %s", got, want) + } + if got := files(t, in.bin); got["pullgate"] != "-rwxr-xr-x "+string(fakePullgate("amd64", "pullgate 0.2.0")) { + t.Errorf("the bin directory holds %q", got) + } + in.checkTmpGone() +} + +// TestInstallStopsOnSIGTERM sends SIGTERM to the script and its programs, +// as Ctrl-C does with SIGINT, while gh checks the attestation. The script +// exits with 1, installs nothing, and removes its temporary directory. +func TestInstallStopsOnSIGTERM(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + before := files(t, in.bin) + marker := filepath.Join(in.dir, "gh-waits") + in.env = append(in.env, "FAKE_GH_WAIT="+marker) + cmd := in.command("--gh", in.gh) + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + var stdout, stderr bytes.Buffer + cmd.Stdout, cmd.Stderr = &stdout, &stderr + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + done := make(chan error, 1) + go func() { done <- cmd.Wait() }() + deadline := time.Now().Add(20 * time.Second) + for { + if _, err := os.Stat(marker); err == nil { + break + } + select { + case err := <-done: + t.Fatalf("the script ended before gh waited: %v\nstdout:\n%s\nstderr:\n%s", err, stdout.String(), stderr.String()) + case <-time.After(10 * time.Millisecond): + } + if time.Now().After(deadline) { + t.Fatal("gh did not start to wait") + } + } + if err := syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM); err != nil { + t.Fatal(err) + } + select { + case <-done: + case <-time.After(20 * time.Second): + _ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) + t.Fatal("the script did not stop on SIGTERM") + } + if code := cmd.ProcessState.ExitCode(); code != 1 { + t.Errorf("exit code %d, want 1\nstderr:\n%s", code, stderr.String()) + } + if want := "pullgate: stopped by a signal; run the script again; nothing was installed (exit 1)"; lastLine(stderr.String()) != want+"\n" && lastLine(stderr.String()) != want { + t.Errorf("last line %q, want %q", lastLine(stderr.String()), want) + } + if after := files(t, in.bin); !maps.Equal(after, before) { + t.Errorf("the bin directory changed") + } + in.checkTmpGone() +} + +// functions writes install.sh without its last line, which starts main, +// into dir, so that a test can load its functions with ".". It returns the +// path of the copy. +func functions(t *testing.T, dir string) string { + t.Helper() + body, ok := strings.CutSuffix(string(readFile(t, "install.sh")), "\nmain \"$@\"\n") + if !ok { + t.Fatal(`install.sh does not end with the line main "$@"`) + } + path := filepath.Join(dir, "functions.sh") + writeFile(t, path, []byte(body+"\n"), 0o600) + return path +} + +// runFunctions runs code with /bin/sh, after it loaded the functions of +// install.sh, with the environment env. +func runFunctions(t *testing.T, lib string, env []string, code string) result { + t.Helper() + cmd := exec.CommandContext(t.Context(), "/bin/sh", "-c", ". \"$0\"\n"+code, lib) + cmd.Env = env + return runCmd(t, cmd) +} + +// TestInstallChecksAsRoot runs the checks of the paths as the script runs +// them as root, with uid 0: then only root may own a path. A test cannot +// make files of root, so it checks that its own files are refused, and +// that the directories of the system pass. +func TestInstallChecksAsRoot(t *testing.T) { + if os.Geteuid() == 0 { + skipOrFail(t, "the test needs files that root does not own") + } + dir := privateDir(t) + lib := functions(t, dir) + own := filepath.Join(dir, "own") + writeFile(t, own, []byte("#!/bin/sh\n"), 0o755) + env := []string{"PATH=" + os.Getenv("PATH")} + asRoot := "uid=0\nowners=root\n" + for _, tt := range []struct { + code string + want string // a part of the last line + }{ + {"check_tree " + own + " own", "pullgate: " + own + " is owned by user " + strconv.Itoa(os.Geteuid()) + + "; it must be owned by root (fix it with chown, or use another path); nothing was installed (exit 1)\n"}, + {"check_tree " + dir + " shared", "it must be owned by root"}, + {"check_entry /tmp own", "pullgate: group or others can write to /tmp; only root may (fix it with chmod go-w, or use another path); nothing was installed (exit 1)\n"}, + } { + r := runFunctions(t, lib, env, asRoot+tt.code) + if r.code != 1 || !strings.Contains(lastLine(r.stderr), tt.want) { + t.Errorf("%s: exit code %d, stderr %q; want 1 and %q", tt.code, r.code, r.stderr, tt.want) + } + } + // The directories of the system: root owns them, and only /tmp, with + // the sticky bit, lets others write. + for _, code := range []string{"check_tree /usr/bin own", "check_tree /tmp shared", "check_tree / own"} { + path := strings.Fields(code)[1] + if info, err := os.Lstat(path); err != nil || !info.IsDir() || info.Sys().(*syscall.Stat_t).Uid != 0 { + skipOrFail(t, "%s is not a directory of root", path) + } + if r := runFunctions(t, lib, env, asRoot+code); r.code != 0 { + t.Errorf("%s: exit code %d, stderr %q; want 0", code, r.code, r.stderr) + } + } +} + +// TestInstallCleansTheEnvironment runs clean_env of the script. It removes +// the variables that change what the programs of the script do, and sets +// LC_ALL=C. As root (a fake id says 0), it also sets the fixed PATH, which +// here is a directory of the test. +func TestInstallCleansTheEnvironment(t *testing.T) { + dir := privateDir(t) + lib := functions(t, dir) + all := append(append([]string{"TAR_OPTIONS"}, loaderVars...), unsafeVars...) + env := []string{"PATH=" + os.Getenv("PATH"), "LC_ALL=de_DE.UTF-8", "IFS=x"} + for _, name := range all { + env = append(env, name+"=/nonexistent/made-up") + } + show := `printf '%s|%s|' "$uid" "$owners"; printf '%s|' "$LC_ALL" "${IFS-unset}"` + for _, name := range all { + show += `; printf '%s|' "${` + name + `-unset}"` + } + wantVars := "C|unset|" + strings.Repeat("unset|", len(all)) + + // As this user: PATH stays. + r := runFunctions(t, lib, env, "clean_env\n"+show+`; printf '%s' "$PATH"`) + uid := strconv.Itoa(os.Geteuid()) + if want := uid + "|root or user " + uid + "|" + wantVars + os.Getenv("PATH"); r.code != 0 || r.stdout != want { + t.Errorf("as user %s: exit code %d, stdout %q, stderr %q; want %q", uid, r.code, r.stdout, r.stderr, want) + } + + // As root: PATH is root_path. + fakeRoot := filepath.Join(dir, "root-bin") + mkdir(t, fakeRoot, 0o700) + writeFile(t, filepath.Join(fakeRoot, "id"), []byte("#!/bin/sh\necho 0\n"), 0o700) + r = runFunctions(t, lib, env, "root_path="+fakeRoot+"\nclean_env\n"+show+`; printf '%s' "$PATH"`) + if want := "0|root|" + wantVars + fakeRoot; r.code != 0 || r.stdout != want { + t.Errorf("as root: exit code %d, stdout %q, stderr %q; want %q", r.code, r.stdout, r.stderr, want) + } + // The real script uses the directories of the system. + if !strings.Contains(string(readFile(t, "install.sh")), "\nroot_path=/usr/sbin:/usr/bin:/sbin:/bin\n") { + t.Error("install.sh does not set root_path=/usr/sbin:/usr/bin:/sbin:/bin") + } +} + +// TestInstallChecksTheUserID: clean_env stops when id -u fails, or prints +// something that is not a user ID. +func TestInstallChecksTheUserID(t *testing.T) { + dir := privateDir(t) + lib := functions(t, dir) + for i, tt := range []struct { + id string // the fake id + want string + }{ + {"echo root", "id -u does not print a user ID; check the program id in ROOT"}, + {"echo 0x0", "id -u does not print a user ID; check the program id in ROOT"}, + {"echo ' 0'", "id -u does not print a user ID; check the program id in ROOT"}, + {"echo -1", "id -u does not print a user ID; check the program id in ROOT"}, + {"true", "id -u does not print a user ID; check the program id in ROOT"}, + {"exit 1", "cannot run id -u; check that ROOT has the program id"}, + } { + fakes := filepath.Join(dir, "fakes"+strconv.Itoa(i)) + mkdir(t, fakes, 0o700) + writeFile(t, filepath.Join(fakes, "id"), []byte("#!/bin/sh\n"+tt.id+"\n"), 0o700) + r := runFunctions(t, lib, []string{"PATH=" + os.Getenv("PATH")}, "root_path="+fakes+"\nclean_env\necho passed") + if want := "pullgate: " + strings.ReplaceAll(tt.want, "ROOT", fakes) + "; nothing was installed (exit 1)\n"; r.code != 1 || lastLine(r.stderr) != want || r.stdout != "" { + t.Errorf("id that runs %q: exit code %d, stdout %q, stderr %q; want 1 and %q", tt.id, r.code, r.stdout, r.stderr, want) + } + } +} + +// TestPinnedGh: the gh that the script downloads is 2.93.0 or newer, and +// the script has a SHA-256 for each CPU. +func TestPinnedGh(t *testing.T) { + script := string(readFile(t, "install.sh")) + value := func(name, pattern string) string { + m := regexp.MustCompile(`(?m)^`+name+`=(`+pattern+`)$`).FindAllStringSubmatch(script, -1) + if len(m) != 1 { + t.Fatalf("install.sh has %d lines %s=%s, want 1", len(m), name, pattern) + } + return m[0][1] + } + num := `(0|[1-9][0-9]*)` + version := value("gh_version", num+`\.`+num+`\.`+num) + if minVersion := value("gh_min_version", num+`\.`+num+`\.`+num); minVersion != "2.93.0" { + t.Errorf("gh_min_version is %s, want 2.93.0", minVersion) + } + var parts [3]int + for i, s := range strings.Split(version, ".") { + parts[i], _ = strconv.Atoi(s) + } + if parts[0] < 2 || (parts[0] == 2 && parts[1] < 93) { + t.Errorf("the pinned gh is %s, want 2.93.0 or newer", version) + } + if value("gh_sha256_amd64", "[0-9a-f]{64}") == value("gh_sha256_arm64", "[0-9a-f]{64}") { + t.Error("gh has the same SHA-256 for amd64 and arm64") + } +} + +// skipOrFail skips the test, or fails it when the CI environment variable +// is set: CI has every program that the tests need. +func skipOrFail(t *testing.T, format string, args ...any) { + t.Helper() + if os.Getenv("CI") != "" { + t.Fatalf("CI is set, so this test must run, but: "+format, args...) + } + t.Skipf(format, args...) +} + +// writeFile writes data to path with mode. It holds syscall.ForkLock while +// the file is open, so that no child process that starts at that time +// gets a copy of the descriptor: then running the file would fail with +// "text file busy" (go.dev/issue/22315). +func writeFile(t *testing.T, path string, data []byte, mode os.FileMode) { + t.Helper() + syscall.ForkLock.RLock() + err := os.WriteFile(path, data, 0o600) + syscall.ForkLock.RUnlock() + if err != nil { + t.Fatal(err) + } + if err := os.Chmod(path, mode); err != nil { + t.Fatal(err) + } +} + +func readFile(t *testing.T, path string) []byte { + t.Helper() + data, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + return data +} + +// readEnv reads the output of env into a map. +func readEnv(t *testing.T, path string) map[string]string { + t.Helper() + env := map[string]string{} + for line := range strings.Lines(string(readFile(t, path))) { + if name, value, ok := strings.Cut(strings.TrimSuffix(line, "\n"), "="); ok { + env[name] = value + } + } + return env +} + +// lastLine returns the last line of s, with its newline. +func lastLine(s string) string { + body := strings.TrimSuffix(s, "\n") + return s[strings.LastIndex(body, "\n")+1:] +} + +// windows returns each run of n elements of s. +func windows(s []string, n int) [][]string { + var w [][]string + for i := 0; i+n <= len(s); i++ { + w = append(w, s[i:i+n]) + } + return w +}