ci: share the C library check and build musl protect-ffi in Alpine

[auxesis]

One script now checks the C library of every Linux release binary

A Linux binary links one C library. Most Linux systems, such as Ubuntu, use glibc, the GNU C library. Alpine Linux uses musl, a smaller C library, and a glibc binary does not load there. So each Linux platform package must contain a binary that links the C library its name claims.

The release workflows check this by reading each binary's NEEDED entries. A NEEDED entry is a line in the binary's dynamic section that names a shared library the system must load with it. A gnu binary must need libc.so.6. A musl binary must not need libc.so.6, and must need libc.musl-x86_64.so.1.

This pull request fixes Linear issue CIP-4284 and Linear issue CIP-4282. It must merge before #1014 releases protect-ffi.

The C library rules now live in one script

Until now, three workflows each had their own copy of the rules: _build-auth-artifacts.yml, auth-preflight.yml and ffi-preflight.yml. A preflight is a workflow that builds the real release packages and tests them, but cannot publish them. Nothing kept the three copies the same, and one had already drifted. The copy in ffi-preflight.yml refused glibc for the musl binary, but it did not require musl, so it accepted a statically linked binary.

scripts/check-c-library.sh <platform> <binary> now holds the rules, and every workflow that checks a Linux binary calls it. It fails for a platform it has no rule for, so a new Linux platform cannot ship unchecked. The two preflights now check out the built commit's scripts/ folder before they download the packages.

scripts/__tests__/check-c-library.test.mjs runs the script with the real readelf on six ELF files. They are a gnu binary, a musl binary, two binaries with long dynamic sections, and two statically linked binaries. The test also checks that every Linux platform package has a rule, and that no workflow keeps its own copy of the rules.

The test writes these ELF files itself, from about 120 lines of JavaScript. I chose this over compiling them because no musl compiler is on the CI runners or on a developer's Mac. I chose it over checked-in binaries because a reviewer cannot read a binary file. The script reads only the NEEDED entries, through the real readelf, so a small ELF file with the same entries is the same input.

I also ran the script by hand on real glibc and musl libraries, compiled in Debian and Alpine. It gave the same answers as it gives for the test's files.

readelf is part of GNU binutils, which every Linux runner has and macOS does not. The script tests run in CI and on Linux, and they are skipped only outside CI when readelf is missing.

Every protect-ffi build now checks its Linux binaries

Before this change, only ffi-preflight.yml checked protect-ffi's C library, and nothing starts that preflight automatically. release.yml builds through _build-ffi-artifacts.yml, so a release could publish a musl binary that links glibc. cipherstash-suite published a glibc-linked @cipherstash/auth-linux-x64-musl 0.44.0 in that way.

Each Linux leg of _build-ffi-artifacts.yml now runs the script after it places the binary and before it packs it, as #1018 did for @cipherstash/auth. scripts/__tests__/ffi-build-artifacts.test.mjs checks the step's position, its Linux condition and the binary it reads.

protect-ffi's musl binary now builds inside Alpine Linux

_build-ffi-artifacts.yml downloaded its musl toolchain from musl.cc. On 2 October 2026, that download timed out from GitHub's runners on six tries in a row. The pinned digest also checked the file without checking who made it.

The linux-x64-musl leg now builds inside node:22-alpine, at the digest that #1018 pinned for @cipherstash/auth. Alpine is a musl system, so its own compiler links musl. The container runs the build script and log that the matrix chooses, with -crt-static so the binary stays dynamically linked to musl. It then places the binary as the other legs do, and loads it with Node.js on musl. The host build steps skip that leg.

The container installs the Rust version that its runner reports, as the other five legs use their runners' Rust. ffi-preflight.yml now also installs the wrapper and the musl package inside the same Alpine image, and loads the native binding. A test checks that all four workflows use one pinned Alpine image.

mise is now pinned in the protect-ffi build, because main fails without it

The first FFI preflight on this branch failed on both gnu legs, at the step that installs zig and cargo-zigbuild. That step did not pin a mise version, so it installed mise 2026.10.0, released on 2 October 2026. That release refuses to install cargo-zigbuild until the root mise.toml's Rust 1.94.1 is installed, and this step never installs it.

Main fails in the same way. FFI preflight run 37079039403 on main, at cb58a7b9, failed both gnu legs at that step with the same mise error. Main's earlier FFI preflight run 36969039169 passed with the same mise, because it built 966be055. That commit has no root mise.toml, which the stack crates import added later that day. integration-protect-ffi.yml still passes, because its bare mise install installs Rust 1.94.1 first.

Both mise steps in _build-ffi-artifacts.yml now pin mise 2026.4.0, the version that the auth and EQL release builds pin. A test checks the pin. Without this commit, a protect-ffi release from #1014 would fail at the same step.

Each new test fails when the code it covers is broken

I broke the code on purpose 31 times and ran the tests each time. This is a mutation check. Each time, at least one test failed, and I then put the code back.

The mutations were these:

• In the script, I dropped each rule, accepted unknown platforms, widened the platform names, removed the error annotation and removed the executable bit.
• I piped readelf straight into grep -q, which can fail open. Only the long dynamic sections catch this, which is why the test has them.
• In the build workflows, I moved the check after packing, ran it on every system, pointed it at the wrong binary and removed it.
• In the Alpine build, I unpinned the image, dropped -crt-static, the load test, the file ownership fix and the build log, and brought back musl.cc.
• In the preflights, I checked out the wrong commit, checked out after the download, removed the Alpine smoke test and changed its image.
• I removed the mise pin from one step and changed it on the other.

Both preflights passed on this branch

• FFI preflight run 37078751162, at commit e2820c20, passed every leg and both smoke tests. That commit has the same files as the merged head.
• Auth preflight run 37078222544, at commit 6e823f63, passed every leg and both smoke tests. The later commits change no auth workflow and do not change the script.

Both smoke jobs printed "links the expected C library" for all three Linux packages, then "smoke OK" and "musl smoke OK".

After the rebase onto c4ab67ac, I ran both preflights again on the head b816cf92. In auth preflight run 37081875739, only the Windows leg failed. Its "Add the Rust target" step timed out after 20 seconds while mise fetched wasm-pack from the GitHub API. This pull request does not change that step. FFI preflight run 37081873328 was still running when this pull request merged.

pnpm test:scripts, pnpm run code:check, actionlint and shellcheck all pass locally. lint-release.yml now also runs shellcheck on the new script.

Three decisions need a reviewer

• integration-protect-ffi.yml also runs mise-action without a mise version. It passes today, because it installs Rust before cargo-zigbuild, so I left it alone.
• This pull request has no changeset. It changes how CI builds and checks the packages, but each package keeps the same files and behaviour.
• The musl leg uses the runner's Rust version, as the other five protect-ffi legs do. The auth build uses the root mise.toml's Rust instead.

Linked issues

This PR fixed #1041 and #1043.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PaY5xYydZUWhv8Nex9Sw8a

[changeset-bot]

⚠️ No Changeset found

Latest commit: b816cf9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[freshtonic]

I approve this change. One script now holds the C library rules, and every build and preflight runs it. This also closes the gap in ffi-preflight.yml, which accepted a static musl binary. The Alpine build follows the pattern that #1018 uses for @cipherstash/auth. On this head commit (e2820c20), all three Linux legs of the FFI preflight passed, and the linux-x64-musl leg was one of them. Thus, the container build, the neon dist placement, the load test inside the container and the new C library step all run correctly.

Before you merge, do these checks:

• The smoke job of that preflight has not started yet, because it waits for the Windows leg. It contains the new Alpine smoke step. That step is the only new step that has not run yet. Make sure that it passes.
• Run Tests (Node 22) and Run Tests (Node 24) fail in languages/typescript/packages/cli/src/__tests__/release-train.test.ts. That test compares the stash version pin in skills/stash-cli/SKILL.md. This pull request does not change either file, so I think the failure is not from this change. Rebase on main, or confirm that main has the same failure.

Small items. They do not block the merge:

• The new checkout step in ffi-preflight.yml uses actions/checkout@v6, but the same step in auth-preflight.yml uses a pinned SHA. This agrees with the other actions in ffi-preflight.yml, so you can keep it. But a SHA pin is better for a workflow that downloads release artifacts.
• In check-c-library.test.mjs, the comment in the executable-bit test says "this reads the committed mode". But statSync reads the mode of the file on disk, not the mode in git. If a local chmod +x is not committed, the test passes locally, and the CI checkout then gets a file that it cannot run. To read the committed mode, use git ls-files -s scripts/check-c-library.sh and look for 100755. The other choice is to change the comment.

The three decisions in the description:

• No changeset: I agree. The packages keep the same files and the same runtime behaviour. Also, no skill mentions musl.cc or the musl toolchain, so no SKILL.md needs a change.
• integration-protect-ffi.yml and its mise version with no pin: I agree that it is a separate change. Please open an issue for it, because mise 2026.10.0 will probably stop that job the next time the path filter starts it.
• The musl leg uses the runner's Rust: this is correct. It keeps all six protect-ffi legs on one Rust version.