Walkthrough

Adds detached OpenPGP signature verification of Node.js SHASUMS256.txt using pinned Node release-team keys, a key-sync CLI and release-time check, JS and Rust verified fetch APIs with tests, and resolver wiring that enables verification for official releases only.

Changes

Node.js SHASUMS OpenPGP Verification

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• pnpm/pnpm#11783: Earlier work introducing verified shasums fetchers and resolver plumbing that this PR builds upon.

Suggested reviewers

• KSXGitHub

Poem

🐰
I hopped through bytes and armored keys,
chased a detached sig across the breeze,
matched issuer ids with a careful nod,
wrote keys in TypeScript and stamped in Rust,
crypto rabbit hums — the SHASUMS pleased!

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

• X
• Mastodon
• Reddit
• LinkedIn

Description

pacquet/crates/crypto-shasums-file/src/lib.rs imports pgp::types::KeyDetails but never uses it,
triggering the unused_imports lint. Pacquet CI runs cargo clippy ... -D warnings, so this will
fail the workflow and block merges.

Code

pacquet/crates/crypto-shasums-file/src/lib.rs[R31-34]

+use pgp::{
+    composed::{Deserializable, DetachedSignature, SignedPublicKey},
+    types::KeyDetails,
+};

Evidence

The file contains an unused KeyDetails import, and the repository’s pacquet CI explicitly treats
warnings as errors during clippy, which makes unused_imports merge-blocking.

pacquet/crates/crypto-shasums-file/src/lib.rs[31-34]
.github/workflows/pacquet-ci.yml[97-99]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`KeyDetails` is imported from `pgp::types` but not used anywhere in the module. Because CI runs clippy with `-D warnings`, this unused import will be treated as an error.
## Issue Context
This was introduced with the new OpenPGP verification logic.
## Fix Focus Areas
- pacquet/crates/crypto-shasums-file/src/lib.rs[31-34]
## Suggested fix
Remove `types::KeyDetails` from the `use pgp::{ ... }` import list (or start using it if it was intended, but there is no current usage).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

update-node-release-keys.mjs only fails when canonical fingerprints are missing from the embedded
list, but does not fail when embedded keys are no longer present in the canonical
nodejs/release-keys list. This can leave removed/revoked Node release keys trusted indefinitely,
undermining the trust anchor used by fetchVerifiedNodeShasums.

Code

crypto/shasums-file/scripts/update-node-release-keys.mjs[R24-35]

+  const embedded = readEmbeddedFingerprints()
+  const missing = fingerprints.filter((fp) => !embedded.includes(fp))
+
+  if (!update) {
+    if (missing.length === 0) {
+      console.log(`✓ Embedded Node.js release keys are up to date (${embedded.length} key(s)).`)
+      return
+    }
+    console.error(`✗ Embedded Node.js release keys are out of date. Missing: ${missing.join(', ')}`)
+    console.error(`Run: node ${path.relative(process.cwd(), fileURLToPath(import.meta.url))} --update`)
+    process.exit(1)
+  }

Evidence

The script’s check mode only computes missing and returns success when missing.length === 0, so
it never detects keys that exist in the embedded file but were removed upstream. Separately,
fetchVerifiedNodeShasums defaults to trusting the embedded NODE_RELEASE_KEYS, so stale embedded
keys remain part of the runtime trust set.

crypto/shasums-file/scripts/update-node-release-keys.mjs[19-35]
crypto/shasums-file/src/verifyNodeShasums.ts[44-59]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`crypto/shasums-file/scripts/update-node-release-keys.mjs` only checks for *missing* upstream fingerprints and reports success if none are missing. If `nodejs/release-keys` removes a fingerprint (e.g., key revocation/rotation), pnpm’s embedded `NODE_RELEASE_KEYS` can still contain it and the release gate will still pass, leaving a stale key trusted.
### Issue Context
The embedded key set is used as the trust anchor for verifying Node’s `SHASUMS256.txt.sig` (via `fetchVerifiedNodeShasums`). Keeping revoked/removed keys trusted weakens the security guarantee of the new signature verification.
### Fix
In check mode, compute both:
- `missing = canonical - embedded`
- `extra = embedded - canonical`
Fail the check if either is non-empty, and print both lists (when present) with the existing “Run --update” hint. Update mode can remain unchanged (it already rewrites from the canonical list, which will drop extra keys).
### Fix Focus Areas
- crypto/shasums-file/scripts/update-node-release-keys.mjs[19-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

In pacquet’s Node SHASUMS verifier, failures while parsing embedded Node.js release public keys are
mapped to SignatureUnreadable, producing the message “Could not read the Node.js SHASUMS
signature” even when the signature is fine. This misclassifies the failure mode and makes
verification incidents harder to diagnose.

Code

pacquet/crates/crypto-shasums-file/src/lib.rs[R265-306]

+fn is_signed_by_trusted_node_release_key(
+    content: &[u8],
+    signature_bytes: &[u8],
+) -> Result<bool, FetchVerifiedNodeShasumsError> {
+    let signature = DetachedSignature::from_bytes(Cursor::new(signature_bytes))
+        .map_err(signature_unreadable)?;
+    for key in trusted_node_release_keys()? {
+        if signature.verify(&key.primary_key, content).is_ok() {
+            return Ok(true);
+        }
+        for subkey in &key.public_subkeys {
+            if signature.verify(subkey, content).is_ok() {
+                return Ok(true);
+            }
+        }
+    }
+    Ok(false)
+}
+
+fn trusted_node_release_keys() -> Result<Vec<SignedPublicKey>, FetchVerifiedNodeShasumsError> {
+    NODE_RELEASE_KEYS.iter().map(read_node_release_key).collect()
+}
+
+fn read_node_release_key(
+    trusted_key: &NodeReleaseKey,
+) -> Result<SignedPublicKey, FetchVerifiedNodeShasumsError> {
+    let (key, _headers) = SignedPublicKey::from_armor_single(trusted_key.armored_key.as_bytes())
+        .map_err(signature_unreadable)?;
+    let actual_fingerprint = key.fingerprint().to_string();
+    let fingerprint_matches = actual_fingerprint.eq_ignore_ascii_case(trusted_key.fingerprint);
+    if !fingerprint_matches {
+        return Err(FetchVerifiedNodeShasumsError::EmbeddedKeyFingerprintMismatch {
+            expected: trusted_key.fingerprint,
+            actual: actual_fingerprint,
+        });
+    }
+    Ok(key)
+}
+
+fn signature_unreadable(error: pgp::errors::Error) -> FetchVerifiedNodeShasumsError {
+    FetchVerifiedNodeShasumsError::SignatureUnreadable { error: Arc::new(error) }
+}

Evidence

The error message for SignatureUnreadable is signature-specific, but the same mapping helper
(signature_unreadable) is used for both signature parsing and embedded key parsing, so a key-parse
failure will emit a misleading signature-parse error.

pacquet/crates/crypto-shasums-file/src/lib.rs[89-105]
pacquet/crates/crypto-shasums-file/src/lib.rs[265-306]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`FetchVerifiedNodeShasumsError::SignatureUnreadable` is used for both (a) parsing the detached signature bytes and (b) parsing the embedded public keys. If an embedded key is malformed, the error message incorrectly claims the SHASUMS *signature* couldn’t be read.
### Issue Context
This is surfaced via the new Node.js SHASUMS signature verification path in `pacquet_crypto_shasums_file` and will be wrapped by `NodeResolverError::FetchVerifiedNodeShasums`.
### Fix Focus Areas
- pacquet/crates/crypto-shasums-file/src/lib.rs[89-105]
- pacquet/crates/crypto-shasums-file/src/lib.rs[265-306]
### Suggested fix
- Introduce a distinct error variant for embedded key parsing (e.g. `EmbeddedKeyUnreadable { error }`) with a message like `Could not read an embedded Node.js release public key: ...`.
- Use that new variant for `SignedPublicKey::from_armor_single(...).map_err(...)`.
- Keep `SignatureUnreadable` for `DetachedSignature::from_bytes(...)` only.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The key update script embeds armored keys by expected fingerprint without verifying the key material
actually has that fingerprint, and the runtime verifiers don’t enforce this binding (TS ignores
fingerprints; Rust only debug_asserts). This reduces defense-in-depth and can let drift checks pass
even if embedded fingerprint metadata and key material diverge, potentially breaking verification
for some releases or trusting unintended key material.

Code

crypto/shasums-file/scripts/update-node-release-keys.mjs[R51-55]

+  const keys = []
+  for (const fp of fingerprints) {
+    const armored = (await (await fetchOk(`${RAW}/keys/${fp}.asc`)).text()).trim()
+    keys.push({ fingerprint: fp, armored })
+  }

Evidence

The generator writes fingerprint+armored key pairs without fingerprint validation, TS verification
ignores the fingerprint field entirely when loading trusted keys, and Rust only checks fingerprint
equality via debug_assert which is disabled in release builds.

crypto/shasums-file/scripts/update-node-release-keys.mjs[51-55]
crypto/shasums-file/src/verifyNodeShasums.ts[19-23]
pacquet/crates/crypto-shasums-file/src/lib.rs[265-273]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`update-node-release-keys.mjs` fetches `keys/<fingerprint>.asc` and writes both the fingerprint string and the fetched armored key into the repo, but it never validates that the armored key’s actual fingerprint matches the expected fingerprint. At runtime, the TS verifier (`verifyNodeShasums.ts`) uses only the armored key material (ignoring the stored fingerprint), and the Rust verifier only `debug_assert!`s fingerprint equality (not enforced in release builds).
This means the repo can end up with a fingerprint/key mismatch that still passes the drift check (which compares only embedded fingerprint strings), and the runtime trust set is effectively “whatever armored keys are embedded”, not “these exact fingerprints”.
## Issue Context
- The embedded key files store both `fingerprint` and `armoredKey`, but the current implementation doesn’t enforce the binding in production.
- This is primarily defense-in-depth / correctness hardening: it prevents silent divergence between expected fingerprints and embedded key material.
## Fix Focus Areas
- crypto/shasums-file/scripts/update-node-release-keys.mjs[51-55]
- crypto/shasums-file/src/verifyNodeShasums.ts[19-23]
- pacquet/crates/crypto-shasums-file/src/lib.rs[265-273]
## Implementation notes
- In `update-node-release-keys.mjs`: after fetching each armored key, parse it (e.g. via `openpgp.readKey`) and compare `key.getFingerprint()` (normalized to uppercase, no spaces) to `fp`; throw if mismatch.
- In TS runtime: when loading `NODE_RELEASE_KEYS`, also validate that each parsed key’s fingerprint matches the embedded `fingerprint` field (only for that bundled key set) and throw a clear `PnpmError` if not.
- In Rust runtime: replace `debug_assert!(fingerprint_matches)` with a real runtime check that returns an error (add an error variant like `KeyFingerprintMismatch { expected, actual }`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

signaturePacketVerifies returns false when a signature packet has no issuerKeyID, so any valid
detached signature lacking issuerKeyID will be rejected and Node SHASUMS verification will fail even
if the signature cryptographically matches a trusted key.

Code

crypto/shasums-file/src/verifyNodeShasums.ts[R95-98]

+  const issuerKeyID = signaturePacket.issuerKeyID
+  if (issuerKeyID == null) return false
+  const keyPacket = keyPackets.find((packet) => packet.getKeyID().equals(issuerKeyID))
+  if (keyPacket == null) return false

Evidence

The new verifier currently hard-fails any signature packet without issuerKeyID by returning false
before attempting cryptographic verification, making verification dependent on optional signature
metadata.

crypto/shasums-file/src/verifyNodeShasums.ts[90-103]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`signaturePacketVerifies()` immediately returns `false` when `signaturePacket.issuerKeyID` is null. This makes signature verification brittle to valid OpenPGP detached signatures that omit issuerKeyID (even if they otherwise verify against a trusted key).
### Issue Context
The verifier already loads all trusted key packets (primary + subkeys) and performs packet-level verification. It can safely fall back to trying verification against all trusted key packets when `issuerKeyID` is absent, without weakening security (verification still requires a cryptographically valid signature).
### Fix Focus Areas
- crypto/shasums-file/src/verifyNodeShasums.ts[90-108]
### Suggested change
- If `issuerKeyID` is present: keep the fast-path lookup by keyID.
- If `issuerKeyID` is missing: attempt `signaturePacket.verify(...)` against **each** trusted key packet until one verifies.
- Keep behavior otherwise identical (still return `false` on verify failures, and only accept when at least one packet verifies).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

In isSignedByTrustedKey(), the Promise.all() try/catch wraps both signature parsing and trusted-key
loading, but the thrown error always claims the SHASUMS signature couldn’t be read. If embedded Node
release keys fail to parse, the resulting incident/error report is misleading and obscures the true
failure mode.

Code

crypto/shasums-file/src/verifyNodeShasums.ts[R72-79]

+  try {
+    ;[signature, keyPackets] = await Promise.all([
+      openpgp.readSignature({ binarySignature: signatureBytes }),
+      loadSigningKeyPackets(trustedKeys),
+    ])
+  } catch (err: unknown) {
+    throw new PnpmError('NODE_SHASUMS_SIGNATURE_INVALID', `Could not read the Node.js SHASUMS signature: ${String(err)}`)
+  }

Evidence

The catch block currently covers both the signature parsing call and the trusted-key loading call,
yet always reports a signature-read failure; key parsing happens inside
loadSigningKeyPackets/readSigningKeyPackets via openpgp.readKey, so key failures are misattributed.

crypto/shasums-file/src/verifyNodeShasums.ts[72-79]
crypto/shasums-file/src/verifyNodeShasums.ts[11-23]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`isSignedByTrustedKey()` wraps both `openpgp.readSignature(...)` and `loadSigningKeyPackets(...)` in a single `try/catch`, but the thrown `PnpmError` message always says it "Could not read the Node.js SHASUMS signature". This is misleading when the failure is actually due to parsing/reading the embedded trusted keys.
### Issue Context
- `loadSigningKeyPackets()` parses trusted armored keys via `openpgp.readKey(...)`, which can throw.
- The current catch block doesn’t distinguish whether the error came from signature parsing or key parsing.
### Fix Focus Areas
- crypto/shasums-file/src/verifyNodeShasums.ts[11-23]
- crypto/shasums-file/src/verifyNodeShasums.ts[65-79]
### Suggested fix
Split the `Promise.all` into two explicit steps (or two `try/catch` blocks) so you can throw:
- a “signature unreadable” message only when `readSignature` fails, and
- a “trusted keys unreadable” (or “could not load trusted Node.js release keys”) message when key loading fails.
Keep the existing error code if you want (`NODE_SHASUMS_SIGNATURE_INVALID`), but make the message accurately reflect which artifact was unreadable.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The Rust pacquet verifier reparses all embedded Node release public keys on every SHASUMS
verification call. This adds avoidable CPU overhead during installs/resolutions that verify Node
SHASUMS multiple times in a process.

Code

pacquet/crates/crypto-shasums-file/src/lib.rs[R261-263]

+fn trusted_node_release_keys() -> Result<Vec<SignedPublicKey>, FetchVerifiedNodeShasumsError> {
+    NODE_RELEASE_KEYS.iter().map(read_node_release_key).collect()
+}

Evidence

The verification loop calls trusted_node_release_keys() and that function parses all embedded keys
via read_node_release_key() on each invocation, with no caching layer.

pacquet/crates/crypto-shasums-file/src/lib.rs[242-263]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`trusted_node_release_keys()` constructs a fresh `Vec<SignedPublicKey>` each time by parsing every armored key, and `is_signed_by_trusted_node_release_key()` calls it for every verification. This can be cached safely since the embedded key list is static.
## Issue Context
- TS implementation caches parsed key packets for the bundled key set.
- Rust path currently reparses on each verification.
## Fix Focus Areas
- pacquet/crates/crypto-shasums-file/src/lib.rs[242-263]
## Implementation notes
- Introduce a static cache (e.g. `std::sync::OnceLock<Vec<SignedPublicKey>>` or `once_cell::sync::Lazy`).
- Parse `NODE_RELEASE_KEYS` once into the cache and iterate borrowed keys during verification.
- Ensure parse failures are surfaced as `FetchVerifiedNodeShasumsError` (you may need a dedicated error variant for key-parse failures rather than reusing `SignatureUnreadable`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

• Verify downloaded Node.js runtime SHASUMS256.txt via detached OpenPGP signature.
• Embed/pin Node release public keys and gate releases on keylist freshness.
• Verify only release channel mirrors; keep hardcoded musl mirror trusted over TLS.

The following are alternative approaches to this PR:

Recommendation: The PR’s approach (verify SHASUMS256.txt.sig against pinned Node release keys) is the best pragmatic fix for the mirror-configurable integrity loop. It preserves mirror compatibility for faithful mirrors, blocks malicious mirrors without requiring new upstream infrastructure, and adds a release-time guard to keep embedded trust roots current. The main alternative worth considering is fetching SHASUMS(+sig) from nodejs.org regardless of mirror; however, that would be a behavioral change that undermines mirror-only environments.

index.ts Export verified SHASUMS fetcher and add verified SHASUMS file API +21/-1

Export verified SHASUMS fetcher and add verified SHASUMS file API

• Exports fetchVerifiedNodeShasums and adds fetchVerifiedNodeShasumsFile for consumers needing verified SHASUMS parsing. Refactors raw SHASUMS fetching to reuse a new parseShasumsFile helper.

crypto/shasums-file/src/index.ts

---

verifyNodeShasums.ts Implement detached SHASUMS signature verification against pinned keys +120/-0

Implement detached SHASUMS signature verification against pinned keys

• Adds fetchVerifiedNodeShasums to fetch SHASUMS256.txt and SHASUMS256.txt.sig and verify the detached signature using openpgp key packets. Uses a packet-level verification path to avoid OpenPGP key-validity-window pitfalls with re-certified keys.

crypto/shasums-file/src/verifyNodeShasums.ts

---

index.ts Verify mirror-provided SHASUMS for release channel Node runtimes +18/-8

Verify mirror-provided SHASUMS for release channel Node runtimes

• Switches integrity fetching to use fetchVerifiedNodeShasumsFile when the Node mirror is repository-configurable and the channel is 'release'. Skips verification for unsigned channels and for the hardcoded unofficial musl mirror (trusted over TLS).

engine/runtime/node-resolver/src/index.ts

---

verifyNodeShasums.ts Add unit tests for SHASUMS signature verification +67/-0

Add unit tests for SHASUMS signature verification

• Adds tests covering valid signatures, untrusted signing keys, tampered SHASUMS content, and missing .sig. Uses openpgp-generated test keys and a simple mocked fetch implementation.

crypto/shasums-file/test/verifyNodeShasums.ts

---

verify-node-runtime-shasums.md Changeset documenting Node runtime SHASUMS signature verification +13/-0

Changeset documenting Node runtime SHASUMS signature verification

• Adds a changeset describing the security issue (mirror-configurable SHASUMS circular trust) and the mitigation (OpenPGP signature verification against embedded Node release keys). Notes musl mirror exception.

.changeset/verify-node-runtime-shasums.md

---

create-release-pr.yml Gate releases on embedded Node release keys freshness +7/-0

Gate releases on embedded Node release keys freshness

• Adds a step to fail release PR creation if embedded Node release keys drift from nodejs/release-keys, preventing silent breakage when new signers are added upstream.

.github/workflows/create-release-pr.yml

---

package.json Add OpenPGP dependencies for SHASUMS verification +3/-1

Add OpenPGP dependencies for SHASUMS verification

• Introduces openpgp as a runtime dependency and @openpgp/web-stream-tools as a dev dependency to support signature verification and test tooling.

crypto/shasums-file/package.json

---

update-node-release-keys.mjs Add script to mirror Node release keys into the repo +74/-0

Add script to mirror Node release keys into the repo

• Adds a script to check/update the generated embedded key list from the canonical nodejs/release-keys repository. Supports a CI/check mode and an explicit update mode.

crypto/shasums-file/scripts/update-node-release-keys.mjs

---

nodeReleaseKeys.ts Embed generated Node.js release team OpenPGP public keys +122/-0

Embed generated Node.js release team OpenPGP public keys

• Adds a generated TypeScript file containing the pinned Node.js release public keys used to verify SHASUMS signatures at runtime. Marked as generated and excluded from spellchecking.

crypto/shasums-file/src/nodeReleaseKeys.ts

---

cspell.json Ignore generated Node keys file and add OpenPGP-related words +7/-0

Ignore generated Node keys file and add OpenPGP-related words

• Excludes nodeReleaseKeys.ts/d.ts from spellchecking and adds dictionary entries for openpgp and subkey terminology.

cspell.json

---

package.json Add workspace scripts to check/update embedded Node release keys +2/-0

Add workspace scripts to check/update embedded Node release keys

• Adds check:node-release-keys and update:node-release-keys scripts to run the key mirroring script in check or update mode.

package.json

---

pnpm-lock.yaml Lock new OpenPGP dependencies +42/-0

Lock new OpenPGP dependencies

• Adds openpgp and @openpgp/web-stream-tools to the lockfile, including catalog entries and resolved package metadata.

pnpm-lock.yaml

---

pnpm-workspace.yaml Add OpenPGP packages to workspace catalog +2/-0

Add OpenPGP packages to workspace catalog

• Adds openpgp and @openpgp/web-stream-tools to the workspace catalog for consistent dependency management across packages.

pnpm-workspace.yaml

---

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.