← Blog

How Oam.js release binaries are signed and verified

August 8, 2026 · updated October 3, 2026

This post first ran as “Why Oam.js ships unsigned, checksummed binaries”, and for every release up to then that was the whole story. It was rewritten for the first signed release, v0.18.0. The address kept its old name so links to it still work.

From v0.18.0 on, every Oam.js release is signed twice over: the release as a whole, by an SSH release key, and the Windows and macOS binaries one by one, by their platforms' own code-signing schemes. The SHA256SUMS manifest still ships, and the installers still refuse anything that does not match it. This post spells the trust model out: what is signed, what gets verified, what each check proves — and, just as important, what it does not.

What is signed, and with what

The release keys' fingerprints, published in the oam repo's SECURITY.md and release-keys/README.md as well as here:

KeyFingerprint
oam-release-k1 (current)SHA256:zB7Aq4Ky/U90VJ4sAEp0e2A65KfQpiyQXJI4FuT2oss
oam-release-k2 (next, offline)SHA256:Uy7nugF5mDzfM/8/fcUti9K+sQMbn/LdRAk+sIbWYs4

What the installer actually verifies

curl -fsSL https://oamjs.org/install.sh | sh, install.ps1 and oam self-update all make the same checks, against release keys they carry with them — embedded in the scripts, compiled into the binary. A key list fetched from the release itself would prove nothing. For a release from v0.18.0 on, they:

The failure paths refuse rather than degrade. A signature that does not verify fails, and so does a signed-era release with no manifest; there is no override for either. The one escape hatch is for a missing tool, not a bad signature: the check needs an ssh-keygen with -Y (OpenSSH 8.1 or later), and OAM_INSECURE_SKIP_SIGNATURE=1 lets a host without one install, loudly. Pointing OAM_INSTALL_BASE at a mirror relaxes nothing either: it requires OAM_VERSION, because the signature is checked against the tag you asked for.

Releases before v0.18.0 were cut before signing existed and have no manifest. For those, the installers check the release's published SHA256SUMS against a digest pinned inside the installer, then the binary against that. A pre-signing tag that is not pinned is refused.

What the installers do not check yet is the binaries' own Authenticode or codesign signature. The signed manifest is what they verify; those platform signatures are for the OS, and for you.

What each check proves — and what it does not

A matching SHA-256 proves you received exactly the bytes the release published. A flipped bit in transit, a truncated download, a proxy serving a stale file — the check catches all of it, loudly. It does not prove who published those bytes: someone in control of the YawLabs/oam GitHub account could upload a malicious binary and a SHA256SUMS that matches it.

The manifest signature closes that gap. That same attacker cannot produce a signature that verifies against the keys the installers carry, because the private half of k1 is not on GitHub. The trust anchor moves from “whoever controls the release page” to “whoever holds the release key”.

Two limits, stated plainly. First, curl | sh trusts oamjs.org to serve the real installer, and the keys inside it are only as good as that delivery. oam self-update is stronger here — its keys are compiled into a binary you already have — and verifying by hand, below, is strongest, because you compare the fingerprint against copies published in more than one place. Second, the macOS signature proves less than it looks: a self-signed identity names a consistent signer, but no one has vouched for it, and Gatekeeper treats it no better than an ad-hoc signature. The Windows signature is the one an OS will vouch for: the certificate is issued to a validated publisher.

The Gatekeeper cost

The canonical channel is the one-line installer, and curl and Homebrew fetches set no quarantine flag, so those installs run normally. A binary downloaded with a browser is quarantined, and without Developer ID and notarization Gatekeeper still refuses its first run. The workaround, after moving it into place:

xattr -d com.apple.quarantine ~/.local/bin/oam

Verify the download first. Clearing the quarantine attribute is you personally asserting the trust a notarized signature would have carried — the wrong move on bytes you have not checked.

Why extra files ship with every release

Alongside the binaries, every release publishes SHA256SUMS; every release since v0.8.1 adds LICENSE, NOTICE and THIRD_PARTY_LICENSES.md; and every release from v0.18.0 on adds RELEASE-MANIFEST and RELEASE-MANIFEST.sig. The manifests are the trust model above. The license files exist because the binary is a binary redistribution of V8, ICU, the Node streams port and ~380 Rust crates, and those licenses require their notices to travel with the bytes. THIRD_PARTY_LICENSES.md reproduces the notices for the Rust crates; NOTICE carries what no cargo tool can see — V8 itself, the 16 third-party trees bundled inside the prebuilt V8 static library, the vendored Node.js sources, the vendored web-platform-tests data.

The installer copies the three license files next to the binary, in ~/.oam/bin/licenses, so the copy on your machine carries its own attribution instead of pointing back at a repo. Best-effort, and honestly so: releases before v0.8.1 shipped no license assets, and on those the installer says so rather than leaving an empty directory that implies otherwise.

Verifying by hand

If you take a binary from the downloads page instead of running the installer, these are the same checks. macOS and Linux — fetch the manifests and the public keys:

curl -fsSLO https://github.com/YawLabs/oam/releases/download/v0.20.1/SHA256SUMS
curl -fsSLO https://github.com/YawLabs/oam/releases/download/v0.20.1/RELEASE-MANIFEST
curl -fsSLO https://github.com/YawLabs/oam/releases/download/v0.20.1/RELEASE-MANIFEST.sig
curl -fsSLO https://raw.githubusercontent.com/YawLabs/oam/main/release-keys/allowed_signers

Check the signature:

ssh-keygen -Y verify -f allowed_signers -I oam-release-k1 \
  -n oam-release -s RELEASE-MANIFEST.sig < RELEASE-MANIFEST

It prints Good "oam-release" signature for oam-release-k1 and the fingerprint of the key that made it. Compare that fingerprint with the table above. That step is the point: allowed_signers comes from the same GitHub account as the release, so it is the fingerprint, checked against a copy published somewhere else, that makes the signature mean anything. (k1 signs from v0.18.0 on; after a key rotation, release-keys/ranges says which key signs which tags.)

Then check that the signed manifest names the release you downloaded — its first two lines are oam-release-manifest v1 and tag v0.20.1 — that SHA256SUMS is byte for byte the rest of it, and the binaries against the sums:

head -2 RELEASE-MANIFEST
tail -n +3 RELEASE-MANIFEST | cmp - SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing

On macOS, codesign -dvv oam-aarch64-apple-darwin shows Authority=oam Code Signing (self-signed) and the runtime flag.

Windows (PowerShell), after fetching the same four files with curl.exe -fsSLO. PowerShell has no < redirect, and piping a file into a native command re-encodes it, which breaks a signature over exact bytes — so hand the verify to cmd:

cmd /c "ssh-keygen -Y verify -f allowed_signers -I oam-release-k1 -n oam-release -s RELEASE-MANIFEST.sig < RELEASE-MANIFEST"
Get-AuthenticodeSignature .\oam-x86_64-pc-windows-msvc.exe | Format-List Status, SignerCertificate
(Get-FileHash .\oam-x86_64-pc-windows-msvc.exe -Algorithm SHA256).Hash.ToLower()
Select-String oam-x86_64-pc-windows-msvc.exe RELEASE-MANIFEST

The Authenticode status should be Valid, with a signer of CN=Yaw Labs LLC. The last two lines compare the binary's hash with its line in the signed manifest; the .ToLower() is there because Get-FileHash prints uppercase and the manifest is lowercase.

A release before v0.18.0 has no RELEASE-MANIFEST, so only the shasum (or Get-FileHash) step applies to it — with the limits of a bare checksum described above.

The current release is v0.20.1. The full table of binaries, sizes and sums — and the OAM_VERSION knob for pinning one — is on the downloads page.