Let's document how to verify a Node.js downloads on the website

[aduh95]

As discussed in nodejs/node#58904 (comment), the way we document how to verify Node.js downloads is not ideal, and there seems to be consensus for switching our recommendation from the public OpenPGP.org server to our own nodejs/release-keys repository. On top of changes in the nodejs/node README, we should also host on the website what is the trusted way to verify a Node.js download.

What we need to provide on the website (presumably on the Downloads page) would be:

• a git commit hash to a revision of nodejs/release-keys that contain keys to all.
• a SHA-256 of the gpg-only-active-keys/pubring.kbx on that revision.

Opening this now in case it involves design changes, but it shouldn't land until after the nodejs/node README is edited (currently it still points to keys.openpgp.org as the recommended source).

[the-gabe]

Adding the commit hash would make the most sense to ensure that it's added to https://nodejs.org/dist/index.json.

My existing automation looks a bit like this for finding the right files for the version I need. Extending this to also fetch the commit hash of what keys to take would make sense, and then from there I can make SHA256's of that which I store in an array to act as TOFU pins for the keys.

        # Check for the latest NodeJS 22 version
        LATEST_NODE=$(curl --tlsv1.3 -s https://nodejs.org/dist/index.json | jq -re '.[] | select(.version | startswith("v22")) | .version' | head -n 1)

        # make and cd dir in tmp
        mkdir /tmp/node-install/
        cd /tmp/node-install/

        # Get SHA256s, signature and binaries for the desired version
        curl -O --tlsv1.3 -s --output /tmp/node-install/SHASUMS256.txt https://nodejs.org/dist/$LATEST_NODE/SHASUMS256.txt
        curl -O --tlsv1.3 -s --output /tmp/node-install/SHASUMS256.txt.sig https://nodejs.org/dist/$LATEST_NODE/SHASUMS256.txt.sig
        curl -O --tlsv1.3 -s --output /tmp/node-install/node-$LATEST_NODE-linux-x64.tar.xz https://nodejs.org/dist/$LATEST_NODE/node-$LATEST_NODE-linux-x64.tar.xz

        # Check SHA256 of the binaries tar, this is done BEFORE gpg checks because it is far less attack surface than GPG
        grep node-v*-linux-x64.tar.xz SHASUMS256.txt | sha256sum -c -
        if [ $? -ne 0 ]; then
          echo "File does not match pinned SHA256 hash. Potential supply chain attack detected on NodeJS CDN."
          exit 1
        fi

[aduh95]

Let me try to rephrase to make sure I understand the proposal. You'd like to see an object such as:

{
    "version": "v24.3.0",
    "date": "2025-06-24",
    "nodejs/release-keys": {
        "commit": "3ead0a2d07b13e469fd97ef39facf6d31993fb71",
        "sha256": "4f8664db3ba7311589efe3697881155f8ba4bb5d36fe84bdfa7e77359408b1bf"
    },
    …
}

Which you could use in your script such as:

set -ex
set -o pipefail

LATEST_NODE=$(curl -s https://nodejs.org/dist/index.json | jq -re 'map(select(.lts))[0]')

PUBRING=$(mktemp)
curl -fsLo "$PUBRING" "https://github.com/nodejs/release-keys/raw/$(echo "$LATEST_NODE" | jq -re '.["nodejs/release-keys"].commit')/gpg-only-active-keys/pubring.kbx"
shasum -a 256 "$PUBRING" | grep -q "$(echo "$LATEST_NODE" | jq -re '.["nodejs/release-keys"].sha256')"

VERSION=$(echo "$LATEST_NODE" | jq -re '.version')
TAR="node-$VERSION-linux-x64.tar.xz"
curl -fso "$TAR" "https://nodejs.org/dist/$VERSION/$TAR"

curl -fs "https://nodejs.org/dist/${VERSION}/SHASUMS256.txt.asc" \
| gpgv --keyring="${PUBRING}" --output - \
| grep -E "$TAR" \
| shasum -c -

rm "$PUBRING"

I wonder if an issue with this approach is that it'd encourage folks to check keys dynamically, but their setup would be much more robust if they have hard-coded the hash 🤔

[the-gabe]

Yeah this seems pretty much what I am on about. The hash of the keyring would be subject to change though within the constraint of a major release as maintainers come/go and keys are rotated, so for that reason I would fetch it dynamically personally and rely on a hardcoded SHA256 of the keyring in my script and use that as a TOFU pin of the keyring. The downside is that it's a potential annoying thing to deal with, but it's worth the extra assurance IMHO.

<------------------------------ my own comments on the signing process as-is ------------------------------>

Ideally this signing process would be refactored to be much more robust, and a build comparison/attestation + shamir secret sharing approach would take place. This way you could have a dedicated signing key for each major release, and in order to sign anything, at least X out of Y maintainers have to approve a signature of a particular SHA256 derived from either the binaries produced or from the source tree as a whole for git tags.

This way maintainers would have the copy of the source tree locally to sign and then also build the binaries locally in order to reproduce what the build system produces, in order to both distrust the build system and other maintainers, eliminating a single maintainer going rogue potentially and doing evil signatures, or a compromised build machine anywhere. It also has the benefit of having a very clear decentralised system for making releases without leaving private keys on a build server somewhere and waiting for it to be stolen. You would have to pwn and/or place multiple maintainers under duress instead of just one to do some damage in this scenario.

[aduh95]

Sharing a secret does not decrease the risk of it leaking, quite the contrary – and in the hypothesis that there is a rogue releaser, having a shared secret would actually help them cover their traces. The plan is not really realistic anyway as we're building on platforms for which we have close to 0 contributors let alone releasers (e.g. Windows).

We're getting far off-track, this issue is meant to discuss about changes to the download page. Changes to the index.json file should be directed at https://github.com/nodejs/nodejs-dist-indexer, and changes to the release process to https://github.com/nodejs/Release. We can continue the discussion there if you want to champion a proposal, I'll be hiding our comments since they are off topic.

[NoWayJA]

So something as critical as this to the entire platform security chain, you are just going to mark as off topic and not even open a new thread.
Feel free to mark this off topic too, but just keep in mind if you don't follow these comments up you really should document the current shortcomings that put all of us nodejs users at risk.
Ouch !!!