feat(runtime): add VP_NODE_SKIP_SIGNATURE_VERIFY escape hatch

Allow skipping PGP signature verification of SHASUMS256.txt via the
VP_NODE_SKIP_SIGNATURE_VERIFY env var, so a future keyring or certificate
issue can be temporarily bypassed without blocking installs. The SHA-256
checksum is still verified (integrity preserved, only authenticity dropped),
and a warning is printed on every skipped install. Mirrors asdf's
NODEJS_CHECK_SIGNATURES and mise's signature opt-out; env-var only, no config
or CI flag, so the secure path stays the unconditional default.

Author: fengmk2

crates/vite_js_runtime/src/runtime.rs

@@ -127,6 +127,17 @@ async fn resolve_shasums_content(
     signature: Option<&ShasumsSignature>,
     archive_filename: &str,
 ) -> Result<String, Error> {
+    // Escape hatch: skip PGP verification entirely (e.g. to work around a stale
+    // keyring or a signature-fetch failure). The SHA-256 checksum still runs, so
+    // this only drops authenticity, not integrity. Warn loudly, including in CI,
+    // since it is a deliberate security downgrade the operator opted into.
+    if vite_shared::EnvConfig::get().node_skip_signature_verify {
+        vite_shared::output::warn(&format!(
+            "PGP signature verification skipped for {archive_filename} \
+             (VP_NODE_SKIP_SIGNATURE_VERIFY set); verifying SHA-256 checksum only"
+        ));
+        return download_text(plain_url).await;
+    }
     let Some(signature) = signature else {
         // No signature is published for this source (e.g. unofficial musl builds).
         log_checksum_only(archive_filename);

crates/vite_shared/src/env_config.rs

@@ -68,6 +68,12 @@ pub struct EnvConfig {
     /// Env: `VP_NODE_DIST_MIRROR`
     pub node_dist_mirror: Option<String>,
 
+    /// Skip PGP signature verification of the Node.js `SHASUMS256.txt` (escape
+    /// hatch); the SHA-256 checksum is still verified.
+    ///
+    /// Env: `VP_NODE_SKIP_SIGNATURE_VERIFY`
+    pub node_skip_signature_verify: bool,
+
     /// Whether running in a CI environment.
     ///
     /// Env: `CI`
@@ -132,6 +138,8 @@ impl EnvConfig {
                 .trim_end_matches('/')
                 .to_string(),
             node_dist_mirror: std::env::var(env_vars::VP_NODE_DIST_MIRROR).ok(),
+            node_skip_signature_verify: std::env::var(env_vars::VP_NODE_SKIP_SIGNATURE_VERIFY)
+                .is_ok(),
             is_ci: std::env::var("CI").is_ok(),
             bypass_shim: std::env::var(env_vars::VP_BYPASS).is_ok(),
             debug_shim: std::env::var(env_vars::VP_DEBUG_SHIM).is_ok(),
@@ -218,6 +226,7 @@ impl EnvConfig {
             vite_plus_home: None,
             npm_registry: "https://registry.npmjs.org".into(),
             node_dist_mirror: None,
+            node_skip_signature_verify: false,
             is_ci: false,
             bypass_shim: false,
             debug_shim: false,
@@ -269,6 +278,7 @@ mod tests {
         assert_eq!(config.npm_registry, "https://registry.npmjs.org");
         assert!(!config.is_ci);
         assert!(!config.bypass_shim);
+        assert!(!config.node_skip_signature_verify);
     }
 
     #[test]

crates/vite_shared/src/env_vars.rs

@@ -27,6 +27,10 @@ pub const NPM_CONFIG_REGISTRY_UPPER: &str = "NPM_CONFIG_REGISTRY";
 /// Node.js distribution mirror URL for downloads.
 pub const VP_NODE_DIST_MIRROR: &str = "VP_NODE_DIST_MIRROR";
 
+/// Skip PGP signature verification of `SHASUMS256.txt` when set (escape hatch).
+/// The SHA-256 checksum is still verified.
+pub const VP_NODE_SKIP_SIGNATURE_VERIFY: &str = "VP_NODE_SKIP_SIGNATURE_VERIFY";
+
 /// Override Node.js version (takes highest priority in version resolution).
 pub const VP_NODE_VERSION: &str = "VP_NODE_VERSION";
 

docs/guide/env.md

@@ -153,3 +153,15 @@ VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist vp env default lts
 # Set it permanently in your shell profile (.bashrc, .zshrc, etc.)
 echo 'export VP_NODE_DIST_MIRROR=https://my-mirror.example.com/nodejs/dist' >> ~/.zshrc
 ```
+
+## Node.js Signature Verification
+
+When installing Node.js from the official `nodejs.org` distribution, Vite+ downloads the PGP-signed `SHASUMS256.txt.asc` and verifies it against the bundled Node.js release keys before trusting any checksum. This protects against a tampered `SHASUMS256.txt` paired with a matching malicious archive. The SHA-256 checksum of the downloaded archive is always verified afterward.
+
+Custom mirrors (`VP_NODE_DIST_MIRROR`) that publish only the plain `SHASUMS256.txt` fall back to checksum-only verification. A mirror that does publish a `.asc` still has its signature verified, and an invalid signature is a hard error.
+
+If a future keyring or certificate issue blocks downloads, set `VP_NODE_SKIP_SIGNATURE_VERIFY` to temporarily bypass PGP verification. The SHA-256 checksum is still verified, and Vite+ prints a warning when the signature check is skipped:
+
+```bash
+VP_NODE_SKIP_SIGNATURE_VERIFY=1 vp env install 22
+```

rfcs/verify-node-shasums-signature.md

@@ -68,7 +68,10 @@ practice (mise has a recurring stream of GPG key-import/encoding failures).
 Vite+ is the only one that verifies the signature in-process with no external
 `gpg`. That is what justifies bundling rPGP and the keyring (~1.2 MiB added to
 the `vp` binary): it brings the strongest guarantee available while keeping the
-zero-dependency, cross-platform install that `vp` requires.
+zero-dependency, cross-platform install that `vp` requires. Like asdf
+(`NODEJS_CHECK_SIGNATURES`) and mise, Vite+ also exposes an opt-out
+(`VP_NODE_SKIP_SIGNATURE_VERIFY`) for when key/certificate issues would
+otherwise block installs; see [Escape hatch](#escape-hatch-skipping-signature-verification).
 
 [asdf-nodejs]: https://github.com/asdf-vm/asdf-nodejs
 [mise]: https://mise.jdx.dev/
@@ -174,6 +177,24 @@ The signature fetch/verify stays outside the content-integrity retry loop, like
 the existing SHASUMS fetch/parse: signature failures are permanent, and
 `download_text` already retries the network layer.
 
+### Escape hatch: skipping signature verification
+
+Setting `VP_NODE_SKIP_SIGNATURE_VERIFY` (to any value) skips PGP verification
+entirely and uses the plain `SHASUMS256.txt`, regardless of `required`. This is
+a deliberate opt-out for the case where a future keyring or certificate problem
+would otherwise block installs, mirroring asdf's `NODEJS_CHECK_SIGNATURES=no`
+and mise's `verify_checksums`/signature settings. Two properties keep it from
+silently weakening the install:
+
+- The SHA-256 checksum of the archive against `SHASUMS256.txt` is still
+  verified, so integrity (archive matches its SHASUMS) is preserved; only
+  authenticity (the SHASUMS came from a Node.js releaser) is dropped.
+- It prints a warning on every skipped install so the weaker mode is visible in
+  logs, not silent.
+
+It is an env-var only switch: there is no config-file or CI flag, keeping the
+secure path the unconditional default.
+
 ## Trust model and limitations
 
 The trust boundary is the curated set of Node.js release keys plus honoring key
@@ -212,6 +233,14 @@ before the trust anchor is updated, and PR CI (the `vite_js_runtime` tests)
 confirms every vendored key still parses. The same script can be run locally to
 refresh the keyring on demand.
 
+### Operator opt-out
+
+`VP_NODE_SKIP_SIGNATURE_VERIFY` (see [Escape hatch](#escape-hatch-skipping-signature-verification))
+lets an operator lower the trust boundary to integrity-only (SHA-256 against
+`SHASUMS256.txt`), forgoing authenticity. It is off by default, requires an
+explicit env var, and warns on every skipped install, so the weaker mode is an
+opt-in choice rather than a silent default.
+
 ### `rsa` advisory
 
 Pulling in `pgp` transitively adds the `rsa` crate, which carries