How Oam.js release binaries are signed and verified
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. Next to the binaries, every release
carries
RELEASE-MANIFEST— the lineoam-release-manifest v1, the linetag <tag>, then the release'sSHA256SUMSlines, verbatim — andRELEASE-MANIFEST.sig, an SSH signature over it (ssh-keygen -Y sign, namespaceoam-release) made with release keyk1. -
Windows. Both
.exeassets carry an Authenticode signature from Azure Artifact Signing, publisher “Yaw Labs LLC”, a verified publisher. Smart App Control accepts it. SmartScreen reputation for a new signature builds up over time, so until it has, SmartScreen may still show an unrecognized-app screen. - macOS. Both binaries are signed with oam's own pinned, self-signed identity, “oam Code Signing (self-signed)”, with the hardened runtime and the JIT entitlements V8 needs. That is not an Apple Developer ID signature, and the binaries are not notarized yet — enrollment is in progress.
- Linux. No OS-level signature. The signed manifest is the integrity check.
The release keys' fingerprints, published in the oam repo's
SECURITY.md
and
release-keys/README.md
as well as here:
| Key | Fingerprint |
|---|---|
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:
-
verify
RELEASE-MANIFEST.sigoverRELEASE-MANIFESTwithssh-keygen -Y verify; -
require the manifest's
tagline to be exactly the tag being installed, so an old, correctly signed release cannot be served as a newer one, and the signing key to be one whose range covers that tag, so a retired or staged key signs nothing; - take the binary's SHA-256 from the signed manifest, hash the download, and die on any disagreement.
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.