feat: support delaying installation of recently published npm packages (#24334)

Adds a minimum package age check (default disabled) so that npm, pnpm
and bun are instructed not to install package versions newer than the
configured threshold. This mitigates supply-chain attacks where a
compromised version is briefly published to the registry.

The threshold is exposed via Options#withMinimumPackageAgeDays(int);
setting it to 0 disables the check.

---------

Co-authored-by: Marco Collovati <marco@vaadin.com>

Author: Artur-

flow-build-tools/src/main/java/com/vaadin/flow/server/frontend/FrontendTools.java

@@ -118,13 +118,18 @@ public class FrontendTools {
     private static final FrontendVersion SUPPORTED_NPM_VERSION = new FrontendVersion(
             SUPPORTED_NPM_MAJOR_VERSION, SUPPORTED_NPM_MINOR_VERSION);
 
-    private static final int SUPPORTED_PNPM_MAJOR_VERSION = 7;
-    private static final int SUPPORTED_PNPM_MINOR_VERSION = 0;
+    // pnpm 10.16.0 is the first version that supports the
+    // minimumReleaseAge setting used to delay installation of newly
+    // published packages as a supply-chain mitigation.
+    private static final int SUPPORTED_PNPM_MAJOR_VERSION = 10;
+    private static final int SUPPORTED_PNPM_MINOR_VERSION = 16;
 
     private static final FrontendVersion SUPPORTED_PNPM_VERSION = new FrontendVersion(
             SUPPORTED_PNPM_MAJOR_VERSION, SUPPORTED_PNPM_MINOR_VERSION);
+    // Bun 1.3.0 is the first version that supports --minimum-release-age
+    // for the same supply-chain mitigation.
     private static final FrontendVersion SUPPORTED_BUN_VERSION = new FrontendVersion(
-            1, 0, 6); // Bun 1.0.6 is the first version with "overrides" support
+            1, 3, 0);
 
     private enum BuildTool {
         NPM("npm", "npm-cli.js"),

flow-build-tools/src/main/java/com/vaadin/flow/server/frontend/Options.java

@@ -166,6 +166,14 @@ public class Options implements Serializable {
 
     private boolean commercialBannerEnabled = false;
 
+    /**
+     * Minimum age, in days, that an npm/pnpm/bun frontend package version must
+     * have before it is allowed to be installed. Defaults to {@code 0}
+     * (disabled); set to a positive value to enable as a mitigation against
+     * malicious packages published to the registry.
+     */
+    private int minimumFrontendPackageAgeDays = 0;
+
     private ApplicationConfiguration applicationConfiguration;
 
     /**
@@ -1095,6 +1103,44 @@ public Options withCommercialBanner(boolean enableCommercialBanner) {
         return this;
     }
 
+    /**
+     * Sets the minimum age (in days) a frontend package version must have
+     * before it is allowed to be installed by npm, pnpm or bun. The intent is
+     * to avoid pulling in brand-new versions that may have been compromised by
+     * a supply-chain attack but not yet detected and removed from the registry.
+     * <p>
+     * For npm this is translated to a {@code --before=<date>} argument; for
+     * pnpm it becomes {@code --config.minimum-release-age=<minutes>} (requires
+     * pnpm &ge; 10.16.0); for bun it becomes
+     * {@code --minimum-release-age=<seconds>} (requires bun &ge; 1.3.0).
+     *
+     * @param minimumFrontendPackageAgeDays
+     *            minimum allowed age in days, or {@code 0} to disable the check
+     * @return this builder
+     * @throws IllegalArgumentException
+     *             if {@code minimumFrontendPackageAgeDays} is negative
+     */
+    public Options withMinimumFrontendPackageAgeDays(
+            int minimumFrontendPackageAgeDays) {
+        if (minimumFrontendPackageAgeDays < 0) {
+            throw new IllegalArgumentException(
+                    "minimumFrontendPackageAgeDays must be >= 0");
+        }
+        this.minimumFrontendPackageAgeDays = minimumFrontendPackageAgeDays;
+        return this;
+    }
+
+    /**
+     * Gets the minimum age (in days) a frontend package version must have
+     * before npm, pnpm or bun is allowed to install it. {@code 0} means the
+     * check is disabled.
+     *
+     * @return the minimum allowed age in days
+     */
+    public int getMinimumFrontendPackageAgeDays() {
+        return minimumFrontendPackageAgeDays;
+    }
+
     /**
      * Gets the frontend dependencies scanner to use. If not is not pre-set,
      * this initializes a new one based on the Options set.

flow-build-tools/src/main/java/com/vaadin/flow/server/frontend/TaskRunNpmInstall.java

@@ -24,11 +24,14 @@
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.StandardCopyOption;
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.ExecutionException;
 import java.util.function.Consumer;
 import java.util.regex.Matcher;
@@ -289,6 +292,9 @@ private void runNpmInstall() throws ExecutionFailedException {
             }
         }
 
+        getMinimumFrontendPackageAgeArgument(options)
+                .ifPresent(npmInstallCommand::add);
+
         postinstallCommand.add("run");
         postinstallCommand.add("postinstall");
 
@@ -425,6 +431,35 @@ static String getToolName(Options options) {
         }
     }
 
+    /**
+     * Builds the install argument that prevents npm, pnpm or bun from
+     * installing frontend package versions newer than
+     * {@link Options#getMinimumFrontendPackageAgeDays()} days. Returns an empty
+     * optional when the check is disabled.
+     */
+    static Optional<String> getMinimumFrontendPackageAgeArgument(
+            Options options) {
+        int days = options.getMinimumFrontendPackageAgeDays();
+        if (days <= 0) {
+            return Optional.empty();
+        }
+        if (options.isEnableBun()) {
+            // bun: --minimum-release-age takes a value in seconds
+            long seconds = (long) days * 24 * 60 * 60;
+            return Optional.of("--minimum-release-age=" + seconds);
+        }
+        if (options.isEnablePnpm()) {
+            // pnpm: minimumReleaseAge is a setting (in minutes), so it has
+            // to be passed via the --config.<name> CLI form, not as a
+            // top-level option
+            long minutes = (long) days * 24 * 60;
+            return Optional.of("--config.minimum-release-age=" + minutes);
+        }
+        // npm: --before takes any Date.parse-able string
+        String before = Instant.now().minus(days, ChronoUnit.DAYS).toString();
+        return Optional.of("--before=" + before);
+    }
+
     private void consumeProcessOutput(Process process,
             Consumer<String> consumer)
             throws IOException, InterruptedException {

flow-build-tools/src/test/java/com/vaadin/flow/server/frontend/FrontendToolsTest.java

@@ -81,7 +81,7 @@ class FrontendToolsTest {
 
     private static final String OLD_PNPM_VERSION = "4.5.0";
 
-    private static final String SUPPORTED_PNPM_VERSION = "7.0.0";
+    private static final String SUPPORTED_PNPM_VERSION = "10.16.0";
 
     private String baseDir;
 

flow-build-tools/src/test/java/com/vaadin/flow/server/frontend/TaskRunNpmInstallTest.java

@@ -24,6 +24,7 @@
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.List;
+import java.util.Optional;
 
 import net.jcip.annotations.NotThreadSafe;
 import org.junit.jupiter.api.BeforeEach;
@@ -763,4 +764,51 @@ private void assumeNPMIsInUse() {
         assumeTrue(getClass().equals(TaskRunNpmInstallTest.class));
     }
 
+    @Test
+    void minimumFrontendPackageAge_defaultIsDisabled_returnsEmpty() {
+        // Default is 0 (disabled) — no flag must be added
+        assertFalse(TaskRunNpmInstall.getMinimumFrontendPackageAgeArgument(
+                new MockOptions(npmFolder)).isPresent());
+        assertFalse(TaskRunNpmInstall
+                .getMinimumFrontendPackageAgeArgument(
+                        new MockOptions(npmFolder).withEnablePnpm(true))
+                .isPresent());
+        assertFalse(TaskRunNpmInstall
+                .getMinimumFrontendPackageAgeArgument(
+                        new MockOptions(npmFolder).withEnableBun(true))
+                .isPresent());
+    }
+
+    @Test
+    void minimumFrontendPackageAge_npm_addsBeforeArgument() {
+        Options npmOptions = new MockOptions(npmFolder)
+                .withMinimumFrontendPackageAgeDays(2);
+        Optional<String> arg = TaskRunNpmInstall
+                .getMinimumFrontendPackageAgeArgument(npmOptions);
+        assertTrue(arg.isPresent());
+        assertTrue(arg.get().startsWith("--before="),
+                "npm should use --before, was: " + arg.get());
+    }
+
+    @Test
+    void minimumFrontendPackageAge_pnpm_addsMinimumReleaseAgeArgument() {
+        Options pnpmOptions = new MockOptions(npmFolder).withEnablePnpm(true)
+                .withMinimumFrontendPackageAgeDays(2);
+        Optional<String> arg = TaskRunNpmInstall
+                .getMinimumFrontendPackageAgeArgument(pnpmOptions);
+        // 2 days = 2880 minutes; pnpm setting form
+        assertEquals("--config.minimum-release-age=2880", arg.orElseThrow());
+    }
+
+    @Test
+    void minimumFrontendPackageAge_bun_addsMinimumReleaseAgeInSeconds() {
+        Options bunOptions = new MockOptions(npmFolder).withEnableBun(true)
+                .withMinimumFrontendPackageAgeDays(2);
+        // 2 days = 172800 seconds
+        assertEquals("--minimum-release-age=172800",
+                TaskRunNpmInstall
+                        .getMinimumFrontendPackageAgeArgument(bunOptions)
+                        .orElseThrow());
+    }
+
 }

flow-plugins/flow-dev-bundle-plugin/src/main/java/com/vaadin/flow/plugin/maven/BuildDevBundleMojo.java

@@ -202,6 +202,17 @@ public class BuildDevBundleMojo extends AbstractMojo
     @Parameter(property = FrontendUtils.PARAM_IGNORE_VERSION_CHECKS, defaultValue = "false")
     private boolean frontendIgnoreVersionChecks;
 
+    /**
+     * Minimum age (in days) a frontend (npm) package version must have before
+     * npm, pnpm or bun is allowed to install it. Mitigates supply-chain attacks
+     * where a compromised version is briefly available on the registry.
+     * Defaults to {@code 0} (disabled); set to a positive value to enable.
+     * Requires pnpm ≥ 10.16.0 or bun ≥ 1.3.0 when those tools are used.
+     */
+    @Parameter(property = "vaadin."
+            + InitParameters.MINIMUM_FRONTEND_PACKAGE_AGE_DAYS, defaultValue = "0")
+    private int minimumFrontendPackageAgeDays;
+
     /**
      * The folder where the META-INF/resources files are copied. Used for
      * finding the StyleSheet referenced css files.
@@ -552,6 +563,11 @@ public boolean isFrontendIgnoreVersionChecks() {
         return frontendIgnoreVersionChecks;
     }
 
+    @Override
+    public int minimumFrontendPackageAgeDays() {
+        return minimumFrontendPackageAgeDays;
+    }
+
     @Override
     public File resourcesOutputDirectory() {
         return resourcesOutputDirectory;

flow-plugins/flow-gradle-plugin/src/main/kotlin/com/vaadin/gradle/GradlePluginAdapter.kt

@@ -336,4 +336,7 @@ internal class GradlePluginAdapter private constructor(
         return config.commercialWithBanner.get()
     }
 
+    override fun minimumFrontendPackageAgeDays(): Int =
+        config.minimumFrontendPackageAgeDays.get()
+
 }

flow-plugins/flow-gradle-plugin/src/main/kotlin/com/vaadin/gradle/VaadinFlowPluginExtension.kt

@@ -343,6 +343,16 @@ public abstract class VaadinFlowPluginExtension @Inject constructor(private val
      */
     public abstract val frontendIgnoreVersionChecks: Property<Boolean>
 
+    /**
+     * Minimum age (in days) a frontend (npm) package version must have before
+     * npm, pnpm or bun is allowed to install it. Mitigates supply-chain
+     * attacks where a compromised version is briefly available on the
+     * registry. Defaults to {@code 0} (disabled); set to a positive value to
+     * enable. Requires pnpm >= 10.16.0 or bun >= 1.3.0 when those tools are
+     * used.
+     */
+    public abstract val minimumFrontendPackageAgeDays: Property<Int>
+
     /**
      * Allows building a version of the application with a commercial banner
      * when commercial components are used without a license key.
@@ -645,6 +655,12 @@ public class PluginEffectiveConfiguration(
             FrontendUtils.PARAM_IGNORE_VERSION_CHECKS
         )
 
+    public val minimumFrontendPackageAgeDays: Provider<Int> =
+        project.getStringProperty(
+            "vaadin.${InitParameters.MINIMUM_FRONTEND_PACKAGE_AGE_DAYS}"
+        ).map(String::toInt)
+            .orElse(extension.minimumFrontendPackageAgeDays.convention(0))
+
     public val npmExcludeWebComponents: Provider<Boolean> = extension
         .npmExcludeWebComponents.convention(false)
 

flow-plugins/flow-maven-plugin/src/main/java/com/vaadin/flow/plugin/maven/BuildFrontendMojo.java

@@ -145,6 +145,17 @@ public class BuildFrontendMojo extends FlowModeAbstractMojo
             + "resources/")
     private File resourcesOutputDirectory;
 
+    /**
+     * Minimum age (in days) a frontend (npm) package version must have before
+     * npm, pnpm or bun is allowed to install it. Mitigates supply-chain attacks
+     * where a compromised version is briefly available on the registry.
+     * Defaults to {@code 0} (disabled); set to a positive value to enable.
+     * Requires pnpm ≥ 10.16.0 or bun ≥ 1.3.0 when those tools are used.
+     */
+    @Parameter(property = "vaadin."
+            + InitParameters.MINIMUM_FRONTEND_PACKAGE_AGE_DAYS, defaultValue = "0")
+    private int minimumFrontendPackageAgeDays;
+
     @Override
     protected void executeInternal()
             throws MojoExecutionException, MojoFailureException {
@@ -303,6 +314,11 @@ public File resourcesOutputDirectory() {
         return resourcesOutputDirectory;
     }
 
+    @Override
+    public int minimumFrontendPackageAgeDays() {
+        return minimumFrontendPackageAgeDays;
+    }
+
     @Override
     public boolean checkRuntimeDependency(String groupId, String artifactId,
             Consumer<String> missingDependencyMessage) {

flow-plugins/flow-maven-plugin/src/main/java/com/vaadin/flow/plugin/maven/DeprecatedPropertyResolver.java

@@ -56,7 +56,8 @@ final class DeprecatedPropertyResolver {
             "vaadin.commercialWithBanner", "vaadin.ci.build",
             "vaadin.force.production.build",
             "vaadin.clean.build.frontend.files", "vaadin.path",
-            "vaadin.useLit1", "vaadin.disableOptionalChaining");
+            "vaadin.useLit1", "vaadin.disableOptionalChaining",
+            "vaadin.npm.minimumFrontendPackageAgeDays");
 
     private DeprecatedPropertyResolver() {
     }