@servicetitan/install 39.2.0 → 40.0.0

package/src/package-manager/npm-package-manager.ts

@@ -1,16 +1,28 @@
 /* eslint-disable no-console */
 import fs from 'fs';
-import { isCI, runCommand, warnUntrustedInstallScripts } from '../utils';
+import {
+    AUDITED_SCRIPTS,
+    getPackagesWithInstallScripts,
+    isCI,
+    runCommand,
+    versionCompare,
+    warnUntrustedInstallScripts,
+} from '../utils';
 import type { DeclaredVersionQuery, InstallArgs, ResolvedVersionQuery } from './package-manager';
 import { PackageManager } from './package-manager';
+import type { TrustedScripts } from './utils';
 import {
-    DEFAULT_ALLOWED_SCRIPTS,
+    filterTrustedScripts,
     logAllowedScripts,
+    parseAllowScripts,
     resolveAllowScripts,
+    resolveMinReleaseAge,
     usesStartup,
     withProjectAllowScripts,
 } from './utils';
 
+const MIN_NPM_VERSION_FOR_RELEASE_AGE = '11.10.0';
+
 interface NpmLockFileEntry {
     version?: string;
     resolved?: string;
@@ -45,8 +57,16 @@ export class NpmPackageManager extends PackageManager<NpmLockFile> {
     }
 
     installPackages(args: InstallArgs = {}, options?: Parameters<typeof runCommand>[2]) {
-        const builtInAllowlist = usesStartup() ? DEFAULT_ALLOWED_SCRIPTS : [];
+        const builtInIgnoredScripts = AUDITED_SCRIPTS.filter(script => script.action === 'ignore');
+        const builtInAllowedScripts = usesStartup()
+            ? AUDITED_SCRIPTS.filter(script => script.action === 'allow')
+            : [];
+        const builtInAllowlist = builtInAllowedScripts.map(script => script.name);
         const allowScripts = resolveAllowScripts(args.allowScripts ?? [], builtInAllowlist);
+        const userAllowlist = Array.isArray(args.allowScripts)
+            ? parseAllowScripts(args.allowScripts)
+            : [];
+        const minReleaseAgeFlags = this.resolveMinReleaseAgeFlags(args);
 
         if (!args.quiet) {
             logAllowedScripts(allowScripts, builtInAllowlist);
@@ -60,6 +80,7 @@ export class NpmPackageManager extends PackageManager<NpmLockFile> {
                 '--fund=false',
                 '--legacy-peer-deps',
                 ...(allowScripts !== true ? ['--ignore-scripts'] : []),
+                ...minReleaseAgeFlags,
                 ...(args.fix ? ['--package-lock-only', '--prefer-dedupe'] : []),
             ],
             options
@@ -69,13 +90,27 @@ export class NpmPackageManager extends PackageManager<NpmLockFile> {
             if (args.fix) {
                 return;
             }
+            let trusted: TrustedScripts | undefined;
+            if (Array.isArray(allowScripts)) {
+                try {
+                    trusted = filterTrustedScripts(
+                        getPackagesWithInstallScripts(),
+                        builtInAllowedScripts,
+                        userAllowlist
+                    );
+                } catch (error) {
+                    console.error(String(error));
+                    console.error('Failed to determine trusted install scripts');
+                    process.exitCode = 1;
+                }
+            }
             /*
              * Rebuild applies when allowScripts is a non-empty explicit list:
              * `true` means npm install already ran every script, `false`
              * means the user opted out.
              */
-            if (Array.isArray(allowScripts) && allowScripts.length > 0) {
-                withProjectAllowScripts(allowScripts, () => this.runRebuild(allowScripts));
+            if (trusted && trusted.specs.length > 0) {
+                withProjectAllowScripts(trusted.names, () => this.runRebuild(trusted.specs));
             }
             /*
              * Warn against the effective allowlist so teams can see which
@@ -84,7 +119,8 @@ export class NpmPackageManager extends PackageManager<NpmLockFile> {
              */
             if (allowScripts !== false) {
                 warnUntrustedInstallScripts(
-                    Array.isArray(allowScripts) ? allowScripts : builtInAllowlist
+                    trusted?.specs ?? builtInAllowlist,
+                    builtInIgnoredScripts
                 );
             }
             /*
@@ -149,6 +185,53 @@ export class NpmPackageManager extends PackageManager<NpmLockFile> {
         }
     }
 
+    private resolveMinReleaseAgeFlags(args: InstallArgs): string[] {
+        if (args.fix) {
+            return [];
+        }
+
+        const resolved = resolveMinReleaseAge(args.minReleaseAge);
+        if (!resolved) {
+            return [];
+        }
+
+        const version = runCommand(this.command, ['--version']).trim();
+        if (versionCompare(version, MIN_NPM_VERSION_FOR_RELEASE_AGE) < 0) {
+            console.warn(
+                `WARNING: npm ${version} does not support minimum release age protection. Installing without it.`
+            );
+            return [];
+        }
+
+        if (this.hasConfiguredMinReleaseAge()) {
+            return [];
+        }
+
+        return [
+            `--min-release-age=${resolved.days}`,
+            ...resolved.exclude.map(pattern => `--min-release-age-exclude=${pattern}`),
+        ];
+    }
+
+    private hasConfiguredMinReleaseAge(): boolean {
+        try {
+            const config = JSON.parse(runCommand(this.command, ['config', 'list', '--json']));
+            if (Number(config['min-release-age']) > 0) {
+                return true;
+            }
+            /*
+             * On npm >=11.10.0 <11.14.0, min-release-age is flattened into an
+             * absolute `before` cutoff date and removed from the config, so
+             * fall back to checking that cutoff instead.
+             */
+            return (
+                typeof config.before === 'string' && new Date(config.before).getTime() < Date.now()
+            );
+        } catch {
+            return false;
+        }
+    }
+
     private runProjectPostinstall(options?: Parameters<typeof runCommand>[2]) {
         try {
             runCommand(this.command, ['run', 'postinstall', '--if-present'], options);

package/src/package-manager/package-manager.ts

@@ -7,6 +7,7 @@ export type AllowScripts = true | false | string[];
 export interface InstallArgs {
     allowScripts?: AllowScripts;
     fix?: boolean;
+    minReleaseAge?: false;
     quiet?: boolean;
 }
 

package/src/package-manager/pnpm-package-manager.ts

@@ -1,7 +1,11 @@
+/* eslint-disable no-console */
 import fs from 'fs';
-import { isCI, runCommand } from '../utils';
+import { isCI, runCommand, versionCompare } from '../utils';
 import type { DeclaredVersionQuery, InstallArgs, ResolvedVersionQuery } from './package-manager';
 import { PackageManager } from './package-manager';
+import { resolveMinReleaseAge } from './utils';
+
+const MIN_PNPM_VERSION_FOR_RELEASE_AGE = '10.16.0';
 
 interface PnpmImporterEntry {
     specifier: string;
@@ -54,6 +58,8 @@ export class PnpmPackageManager extends PackageManager<PnpmLockFile> {
     }
 
     installPackages(args: InstallArgs = {}, options?: Parameters<typeof runCommand>[2]) {
+        this.warnIfMinReleaseAgeNotConfigured(args);
+
         try {
             runCommand(
                 this.command,
@@ -94,6 +100,46 @@ export class PnpmPackageManager extends PackageManager<PnpmLockFile> {
             importer?.optionalDependencies?.[dependency];
         return entry ? stripPeerDependencySuffix(entry.version) : undefined;
     }
+
+    private warnIfMinReleaseAgeNotConfigured(args: InstallArgs) {
+        if (args.fix) {
+            return;
+        }
+
+        if (!resolveMinReleaseAge(args.minReleaseAge)) {
+            return;
+        }
+
+        const version = runCommand(this.command, ['--version']).trim();
+        if (versionCompare(version, MIN_PNPM_VERSION_FOR_RELEASE_AGE) < 0) {
+            console.warn(
+                `WARNING: pnpm ${version} does not support minimum release age protection. Installing without it.`
+            );
+            return;
+        }
+
+        if (this.hasConfiguredMinReleaseAge()) {
+            return;
+        }
+
+        console.warn(
+            'WARNING: this project does not enforce a minimum release age for pnpm installs. Configure minimumReleaseAge in pnpm-workspace.yaml.'
+        );
+    }
+
+    /*
+     * `pnpm config list --json` reports this key as `minimum-release-age` on
+     * pnpm <11 and `minimumReleaseAge` on pnpm >=11, so both are checked.
+     */
+    private hasConfiguredMinReleaseAge(): boolean {
+        try {
+            const config = JSON.parse(runCommand(this.command, ['config', 'list', '--json']));
+            const configuredAge = config.minimumReleaseAge ?? config['minimum-release-age'];
+            return Number(configuredAge) > 0;
+        } catch {
+            return false;
+        }
+    }
 }
 
 function stripPeerDependencySuffix(version: string): string {

package/src/package-manager/utils/filter-trusted-scripts.ts

@@ -0,0 +1,44 @@
+import type { AuditedScript } from '../../utils';
+import { versionCompare } from '../../utils';
+
+export interface InstallScript {
+    name: string;
+    version: string;
+}
+
+export interface TrustedScripts {
+    /** Trusted package name or <name>@<version> */
+    specs: string[];
+    /** Bare names for all trusted packages */
+    names: string[];
+}
+
+export function filterTrustedScripts(
+    installScripts: InstallScript[],
+    builtInAllowlist: AuditedScript[],
+    userAllowlist: string[]
+): TrustedScripts {
+    const specs = new Set<string>();
+    const names = new Set<string>();
+
+    for (const { name, version } of installScripts) {
+        const allowlistEntry = builtInAllowlist.find(entry => entry.name === name);
+        if (!allowlistEntry) {
+            continue;
+        }
+        if (!allowlistEntry.maximumVersion) {
+            specs.add(name);
+            names.add(name);
+        } else if (versionCompare(version, allowlistEntry.maximumVersion) <= 0) {
+            specs.add(`${name}@${version}`);
+            names.add(name);
+        }
+    }
+
+    for (const name of userAllowlist) {
+        specs.add(name);
+        names.add(name);
+    }
+
+    return { specs: [...specs], names: [...names] };
+}

package/src/package-manager/utils/index.ts

@@ -1,5 +1,7 @@
+export * from './filter-trusted-scripts';
 export * from './log-allowed-scripts';
 export * from './parse-allow-scripts';
 export * from './resolve-allow-scripts';
+export * from './resolve-min-release-age';
 export * from './uses-startup';
 export * from './with-project-allow-scripts';

package/src/package-manager/utils/resolve-allow-scripts.ts

@@ -1,14 +1,6 @@
 import type { AllowScripts } from '../package-manager';
 import { parseAllowScripts } from './parse-allow-scripts';
 
-export const DEFAULT_ALLOWED_SCRIPTS = [
-    '@servicetitan/startup',
-    'cypress',
-    'msw',
-    'nx',
-    'tree-sitter',
-];
-
 export function resolveAllowScripts(value: AllowScripts, builtInAllowlist: string[]): AllowScripts {
     if (value === true || value === false) {
         return value;

package/src/package-manager/utils/resolve-min-release-age.ts

@@ -0,0 +1,16 @@
+const DEFAULT_MIN_RELEASE_AGE_DAYS = 3;
+const DEFAULT_MIN_RELEASE_AGE_EXCLUDE = ['@servicetitan/*'];
+
+export interface ResolvedMinReleaseAge {
+    days: number;
+    exclude: string[];
+}
+
+export function resolveMinReleaseAge(
+    minReleaseAge: false | undefined
+): ResolvedMinReleaseAge | false {
+    if (minReleaseAge === false) {
+        return false;
+    }
+    return { days: DEFAULT_MIN_RELEASE_AGE_DAYS, exclude: DEFAULT_MIN_RELEASE_AGE_EXCLUDE };
+}

package/src/utils/audited-scripts.ts

@@ -0,0 +1,92 @@
+export interface AuditedScript {
+    name: string;
+    action: 'allow' | 'ignore';
+    maximumVersion?: string;
+    note?: string;
+}
+
+export const AUDITED_SCRIPTS: AuditedScript[] = [
+    // Trusted to run their install scripts, up to the audited version.
+    ...[
+        {
+            name: '@servicetitan/startup',
+            note: 'Applies patch-package patches to installed dependencies',
+        },
+        {
+            name: 'cypress',
+            maximumVersion: '16.0.0',
+            note: "Downloads Cypress's platform-specific test runner binary",
+        },
+        {
+            name: 'msw',
+            maximumVersion: '2.15.0',
+            note: "Regenerates the mock service worker script into the project's configured workerDirectory, no-op unless that's set",
+        },
+        {
+            name: 'nx',
+            maximumVersion: '23.2.1',
+            note: 'Verifies native platform support and updates the Nx Cloud client if the workspace uses Nx Cloud',
+        },
+        {
+            name: 'tree-sitter',
+            maximumVersion: '0.25.1',
+            note: 'Installs a prebuilt native binary via node-gyp-build, compiling from source as a fallback',
+        },
+    ].map((entry: Omit<AuditedScript, 'action'>) => ({ ...entry, action: 'allow' as const })),
+
+    // Have install scripts, but don't need them to function correctly.
+    ...[
+        {
+            name: '@parcel/watcher',
+            note: 'Installs platform-specific binary via optionalDependencies, install script is a legacy fallback',
+        },
+        {
+            name: '@progress/kendo-licensing',
+            note: 'Validates Kendo UI license key, not needed for functionality',
+        },
+        {
+            name: '@scarf/scarf',
+            note: 'Sends anonymous analytics/telemetry to Scarf, usage-tracking mechanism with no functional purpose',
+        },
+        {
+            name: '@swc/core',
+            note: 'Installs platform-specific binary via optionalDependencies, postinstall is a legacy fallback',
+        },
+        {
+            name: '@tree-sitter-grammars/tree-sitter-yaml',
+            note: 'Ships prebuilds for all supported targets via node-gyp-build, install script is a source-compile fallback',
+        },
+        {
+            name: '@vaadin/vaadin-usage-statistics',
+            note: "Toggles Vaadin's development-time telemetry, no effect on functionality",
+        },
+        {
+            name: 'contentful',
+            note: 'In 9.3.x, printed a message announcing that v10 was available, no functional purpose; no install script at all since 9.4.0',
+        },
+        {
+            name: 'core-js-pure',
+            note: 'Prints a donation/sponsorship banner to the console, no functional purpose',
+        },
+        {
+            name: 'core-js',
+            note: 'Prints a donation/sponsorship banner to the console, no functional purpose',
+        },
+        {
+            name: 'es5-ext',
+            note: 'Displays politically motivated message targeted at Russian developers, no effect on functionality',
+        },
+        {
+            name: 'esbuild',
+            note: 'Installs platform-specific binary via optionalDependencies, postinstall is a legacy fallback',
+        },
+        {
+            name: 'tree-sitter-json',
+            note: 'Ships prebuilds for all supported targets via node-gyp-build, install script is a source-compile fallback',
+        },
+        {
+            name: 'unrs-resolver',
+            note: 'Installs platform-specific binary via optionalDependencies, postinstall is a legacy fallback',
+        },
+    ].map((entry: Omit<AuditedScript, 'action'>) => ({ ...entry, action: 'ignore' as const })),
+];

package/src/utils/get-packages-with-install-scripts.ts

@@ -16,14 +16,10 @@ const SELECTORS = ['preinstall', 'install', 'postinstall']
     .join(',');
 
 export function getPackagesWithInstallScripts(): PackageWithScript[] {
-    try {
-        const result = runCommand('npm', ['query', SELECTORS, '--json']);
-        return JSON.parse(result).map(({ location, name, version }: PackageWithScript) => ({
-            location,
-            name,
-            version,
-        }));
-    } catch {
-        return [];
-    }
+    const result = runCommand('npm', ['query', SELECTORS, '--json']);
+    return JSON.parse(result).map(({ location, name, version }: PackageWithScript) => ({
+        location,
+        name,
+        version,
+    }));
 }

package/src/utils/index.ts

@@ -1,3 +1,4 @@
+export * from './audited-scripts';
 export * from './ci';
 export * from './debug';
 export * from './find-up';
@@ -8,4 +9,5 @@ export * from './git';
 export * from './npm';
 export * from './os';
 export * from './read-json';
+export * from './version-compare';
 export * from './warn-untrusted-install-scripts';

package/src/utils/version-compare.ts

@@ -0,0 +1,34 @@
+export function versionCompare(version: string, otherVersion: string): -1 | 0 | 1 {
+    const [versionCore, versionPrerelease] = splitPrerelease(version);
+    const [otherCore, otherPrerelease] = splitPrerelease(otherVersion);
+
+    const parts = parseVersion(versionCore);
+    const otherParts = parseVersion(otherCore);
+
+    const length = Math.max(parts.length, otherParts.length);
+    for (let i = 0; i < length; i++) {
+        const part = parts[i] ?? 0;
+        const otherPart = otherParts[i] ?? 0;
+        if (part !== otherPart) {
+            return part > otherPart ? 1 : -1;
+        }
+    }
+
+    /*
+     * Same core version: a pre-release build (e.g. "-canary.5") has lower
+     * precedence than the plain release it precedes.
+     */
+    if (!!versionPrerelease === !!otherPrerelease) {
+        return 0;
+    }
+    return versionPrerelease ? -1 : 1;
+}
+
+function splitPrerelease(version: string): [core: string, prerelease: string | undefined] {
+    const [core, ...prerelease] = version.trim().split('-');
+    return [core, prerelease.length > 0 ? prerelease.join('-') : undefined];
+}
+
+function parseVersion(version: string): number[] {
+    return version.split('.').map(part => parseInt(part, 10) || 0);
+}

package/src/utils/warn-untrusted-install-scripts.ts

@@ -1,30 +1,32 @@
 /* eslint-disable no-console */
+import type { AuditedScript } from './audited-scripts';
 import { getPackagesWithInstallScripts } from './get-packages-with-install-scripts';
+import { versionCompare } from './version-compare';
 
-// These packages have scripts, but don't need them to function correctly.
-
-const IGNORE = [
-    '@parcel/watcher', // Installs platform-specific binary via optionalDependencies, install script is a legacy fallback
-    '@progress/kendo-licensing', // Validates Kendo UI license key, not needed for functionality
-    '@scarf/scarf', // Sends anonymous analytics/telemetry to Scarf, usage-tracking mechanism with no functional purpose
-    '@swc/core', // Installs platform-specific binary via optionalDependencies, postinstall is a legacy fallback
-    '@tree-sitter-grammars/tree-sitter-yaml', // Ships prebuilds for all supported targets via node-gyp-build, install script is a source-compile fallback
-    '@vaadin/vaadin-usage-statistics', // Toggles Vaadin's development-time telemetry, no effect on functionality
-    'contentful', // v9 printed a message announcing that v10 was available, no functional purpose
-    'core-js-pure', // Prints a donation/sponsorship banner to the console, no functional purpose
-    'core-js', // Prints a donation/sponsorship banner to the console, no functional purpose
-    'es5-ext', // Displays politically motivated message targeted at Russian developers, no effect on functionality
-    'esbuild', // Installs platform-specific binary via optionalDependencies, postinstall is a legacy fallback
-    'less', // Installs Playwright browsers for Less's own test suite
-    'tree-sitter-json', // Ships prebuilds for all supported targets via node-gyp-build, install script is a source-compile fallback
-    'unrs-resolver', // Installs platform-specific binary via optionalDependencies, postinstall is a legacy fallback
-];
-
-export function warnUntrustedInstallScripts(allowedScripts: string[]) {
-    const packages = getPackagesWithInstallScripts();
-    const trustedOrIgnored = new Set([...allowedScripts, ...IGNORE]);
-    const untrusted = packages.filter(({ location, name }) => {
-        return !!location && !trustedOrIgnored.has(name);
+export function warnUntrustedInstallScripts(allowedScripts: string[], ignored: AuditedScript[]) {
+    let packages: ReturnType<typeof getPackagesWithInstallScripts>;
+    try {
+        packages = getPackagesWithInstallScripts();
+    } catch (error) {
+        console.warn(`WARNING: Unable to check for untrusted install scripts: ${error}`);
+        return;
+    }
+    const untrusted = packages.filter(({ location, name, version }) => {
+        if (
+            !location ||
+            allowedScripts.includes(name) ||
+            allowedScripts.includes(`${name}@${version}`)
+        ) {
+            return false;
+        }
+        const ignoredEntry = ignored.find(entry => entry.name === name);
+        if (!ignoredEntry) {
+            return true;
+        }
+        return (
+            !!ignoredEntry.maximumVersion &&
+            versionCompare(version, ignoredEntry.maximumVersion) > 0
+        );
     });
 
     if (untrusted.length === 0) {