chore: switch to official release-keys repo to verify Node.js artefacts

[aduh95]

Description

Instead of maintaining a separate list of keys and expect to find them on public servers, let's switch to the official keyring and use the smaller gpgv tool.

Motivation and Context

https://github.com/nodejs/node?tab=readme-ov-file#verifying-binaries
nodejs/unofficial-builds#216

Testing Details

Example Output(if appropriate)

Types of changes

• Documentation
• Version change (Update, remove or add more Node.js versions)
• Variant change (Update, remove or add more variants, or versions of variants)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Other (none of the above)

Checklist

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING.md document.
• All new and existing tests passed.

[nschonni]

@yosifkit @tianon I think one of you had previously flagged some issues with switching to keyrings for the official images, or did I misremember that?

[yosifkit]

Just like any file downloaded in the Dockerfile, this would need to be verified by a sha256sum embedded in the Dockerfile (at a minimum) in order to be acceptable to Docker Official Images. See https://github.com/docker-library/official-images/tree/3b4779967d1c2e369aeae1c8533d12f5a9b4df81#image-build.

In many instances, we also recommend checking that only the expected keys exist in the keyring (or maybe that was only when adding them to an apt keyring). cc @tianon

[aduh95]

The content of the keyring is validated in https://github.com/nodejs/release-keys/actions/runs/20075780501/workflow#L64, do you know if that's good enough?

[aduh95]

I've added a step that checks the pubring only contains the expected keys, PTAL

[yosifkit]

@yosifkit @tianon I think one of you had previously flagged some issues with switching to keyrings for the official images, or did I misremember that?

I think you might be referring to #1509 (comment)

[nschonni]

Maybe there is a way in the middle, where the script grabs and parses the keyring, but the image keeps the valid/current keys embedded in the Dockerfile we send upstream

[tianon]

I think you might be referring to #1509 (comment)

That's the one that's most directly pertinent to docker-node -- see also nodejs/node#58979 (comment), nodejs/node#58904 (comment), nodejs/node#39227 (comment) 😅

[tianon]

I think you might be referring to #1509 (comment)

That's the one that's most directly pertinent to docker-node -- see also nodejs/node#58979 (comment), nodejs/node#58904 (comment), nodejs/node#39227 (comment) 😅

To quote nodejs/node#58979 (comment):

"Just trust this precompiled binary bundle of key data" is not exactly something that fills me with warm fuzzies 😅 -- how would I, as a user, verify the contents of pubring.kbx? How would I know which parts of it are relevant for a given Node.js release?

And nodejs/node#39227 (comment):

IMO, https://github.com/nodejs/release-keys would be a very interesting place to include a bit more (programmatically accessible such as symlinks in folders or a JSON doc) metadata about how the keys related to releases, such as which are expected to be actively signing new releases of each version track vs which keys have been used historically to sign releases for each track and aren't expected to sign new releases (instead of just a big bundle of keys for everyone both past and present).

Having that sort of metadata/organization would make something like #1511 much easier to implement, but would also generally reduce the possibility of something like an outdated key being compromised creating a worry for new releases. 👀

As it stands, https://github.com/nodejs/release-keys is functionally not much different from the KEYS files that are common in Apache projects, albeit with some added scaffolding to help ease consumption. 😅

See also https://github.com/docker-library/faq#how-can-i-use-a-keys-file-for-verifying-pgp-signatures

[Copilot]

Pull request overview

Updates the Node.js artifact verification flow in this repo’s generated Dockerfiles to use the official nodejs/release-keys keyring (downloaded + SHA256-pinned) and gpgv, replacing the prior per-key keyserver fetch approach.

Changes:

• Replace Node.js keyserver-based key fetching with a pinned pubring.kbx keyring download + SHA256 verification, and verify SHASUMS256.txt.asc with gpgv.
• Update the key update workflow to persist the resolved keyring URL and its SHA256 to keys/.
• Remove the legacy keys/node.keys list and update Dockerfile generation accordingly.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
update.sh	Stops injecting NODE_KEYS and instead injects Yarn keys plus Node.js keyring URL/hash into generated Dockerfiles.
update-keys.sh	Updates the workflow to resolve the official Node.js keyring URL and store its SHA256 for pinning.
keys/nodejs.url	Stores the resolved/pinned release-keys raw URL for pubring.kbx.
keys/nodejs.shasum	Stores the SHA256 checksum line used to validate the downloaded pubring.kbx.
keys/node.keys	Removes the legacy list of individual Node.js release key fingerprints.
Dockerfile-slim.template	Switches Node verification to gpgv + keyring download/sha256 validation.
Dockerfile-debian.template	Switches Node verification to gpgv + keyring download/sha256 validation.
Dockerfile-alpine.template	Switches Node verification to gpgv + keyring download/sha256 validation (source-build path).
25/trixie/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 on trixie.
25/trixie-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 slim on trixie.
25/bullseye/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 on bullseye.
25/bullseye-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 slim on bullseye.
25/bookworm/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 on bookworm.
25/bookworm-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 slim on bookworm.
25/alpine3.23/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 on alpine3.23 (source-build path).
25/alpine3.22/Dockerfile	Applies the new gpgv + keyring verification flow for Node 25 on alpine3.22 (source-build path).
24/trixie/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 on trixie.
24/trixie-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 slim on trixie.
24/bullseye/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 on bullseye.
24/bullseye-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 slim on bullseye.
24/bookworm/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 on bookworm.
24/bookworm-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 slim on bookworm.
24/alpine3.23/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 on alpine3.23 (source-build path).
24/alpine3.22/Dockerfile	Applies the new gpgv + keyring verification flow for Node 24 on alpine3.22 (source-build path).
22/trixie/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 on trixie.
22/trixie-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 slim on trixie.
22/bullseye/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 on bullseye.
22/bullseye-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 slim on bullseye.
22/bookworm/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 on bookworm.
22/bookworm-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 slim on bookworm.
22/alpine3.23/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 on alpine3.23 (source-build path).
22/alpine3.22/Dockerfile	Applies the new gpgv + keyring verification flow for Node 22 on alpine3.22 (source-build path).
20/trixie/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 on trixie.
20/trixie-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 slim on trixie.
20/bullseye/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 on bullseye.
20/bullseye-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 slim on bullseye.
20/bookworm/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 on bookworm.
20/bookworm-slim/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 slim on bookworm.
20/alpine3.23/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 on alpine3.23 (source-build path).
20/alpine3.22/Dockerfile	Applies the new gpgv + keyring verification flow for Node 20 on alpine3.22 (source-build path).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aduh95]

Is there any unadressed objections? If I don't hear any, I plan to land this before 26.0.0 is released

[nschonni]

@aduh95 I'm just blocking this, because we need agreement from the Docker hub people (@yosifkit, @tianon, or @LaurentGoderre) otherwise we can't proceed. If one of them agrees, you can dismiss this review

[nschonni]

I kind of want to try to see if this could be used to keep the embedded fingerprints in the Dockerfiles by droping the node.keys and doing this each time as part of the bigger update.sh. I'll see if I can figure that out later

[aduh95]

keep the embedded fingerprints in the Dockerfiles by droping the node.keys and doing this each time as part of the bigger update.sh

Hum I think that's already what's happening:

docker-node/25/bookworm/Dockerfile

Line 22 in fc4d9bd

&& [ "$(gpg --no-default-keyring --keyring "$GNUPGHOME/pubring.kbx" --list-keys --with-colons | awk -F: '{ if (print_next_line) { print $10; print_next_line=0; } else if ($1=="pub") print_next_line=1; }')" = "$(printf '5BE8A3F6C8A5C01D106C0AD820B1A390B168D356\nDD792F5973C6DE52C432CBDAC77ABFA00DDBF2B7\nCC68F5A3106FF448322E48ED27F5E38D5B0A215F\n8FCCA13FEF1D0C2E91008E09770F7A9A5AE15600\n890C08DB8579162FEE0DF9DB8BEAB4DFCF555EF4\nC82FA3AE1CBEDC6BE46B9360C43CEC45C17AB93C\n108F52B48DB57BB0CC439B2997B01419BD92F80A\nA363A499291CBBC940DD62E41F10027AF002F8B0\n')" ] \

I don't think dropping the node.keys is desirable, but maybe I misunderstand what you mean.