@gkiely/safe-install 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grant Kiely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# safe-install
+
+Run npm installs with dependency lifecycle scripts disabled by default, then
+rebuild only the packages you explicitly trust.
+
+`safe-install` is for npm projects that want trusted dependency installs without
+switching package managers.
+
+## Why
+
+npm lifecycle scripts can run arbitrary code during install. Setting
+`ignore-scripts=true` blocks that whole class of install-time execution, but it
+also breaks packages that legitimately need `postinstall`, `install`, or
+`preinstall` scripts to build native bindings, download binaries, or finish
+setup.
+
+This package keeps the default install locked down and moves script execution
+behind a reviewed allowlist in `package.json`.
+
+## Setup
+
+1. Add this to `.npmrc`:
+
+```txt
+ignore-scripts=true
+```
+
+2. Install `safe-install` without running dependency scripts:
+
+```sh
+npm i --ignore-scripts -D safe-install
+```
+
+3. Add scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "safe-install": "safe-install"
+  }
+}
+```
+
+4. Find dependencies that declare install-time scripts:
+
+```sh
+npm run safe-install -- find
+```
+
+5. Review the output, then add trusted packages to `package.json`. You can also
+enable `blockExoticSubDeps` to fail installs when transitive dependencies point
+outside the npm registry with `git:`, `file:`, `link:`, or remote tarball URL
+specifiers.
+
+```json
+{
+  "blockExoticSubDeps": true,
+  "trustedDependencies": [
+    "esbuild",
+    "sharp"
+  ]
+}
+```
+
+6. Use `safe-install` for future installs:
+
+```sh
+npm run safe-install
+```
+
+## What `safe-install` does
+
+`safe-install` runs npm install with scripts blocked, then runs install scripts only for packages listed in
+`trustedDependencies`.
+
+If `blockExoticSubDeps` is set to `true` in `package.json`, `safe-install` also
+fails the install before rebuilding trusted dependencies when a transitive
+dependency points outside the npm registry with a `git:`, `file:`, `link:`, or
+remote tarball URL specifier.
+
+Equivalent manual flow:
+
+```sh
+npm install --ignore-scripts
+npm rebuild --ignore-scripts=false esbuild sharp
+```
+
+## Notes
+
+Only add a package to `trustedDependencies` after reviewing why it needs an
+install script. This does not make dependency scripts safe; it makes the trust
+decision explicit and version-controlled.

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+type PackageJson = {
+    blockExoticSubDeps?: unknown;
+    trustedDependencies?: unknown;
+};
+type LockPackage = {
+    dependencies?: Record<string, string>;
+    hasInstallScript?: boolean;
+    link?: boolean;
+    name?: string;
+    scripts?: Record<string, unknown>;
+};
+type PackageLock = {
+    packages?: Record<string, LockPackage>;
+};
+export declare function getTrustedDependencies(pkg: PackageJson): string[];
+export declare function findInstallScriptDependencies(packageLock: PackageLock, trustedDependencies?: readonly string[]): string[];
+type SafeInstallConfig = {
+    blockExoticSubdeps: boolean;
+};
+export declare function getSafeInstallConfig(pkg: PackageJson): SafeInstallConfig;
+export declare function assertNoBlockedExoticSubdeps(config: SafeInstallConfig, packageLock: PackageLock): void;
+export declare function findCommand(): void;
+export declare function installCommand(): void;
+export declare function main(args?: string[]): void;
+export {};

package/dist/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const installScriptNames = ["preinstall", "install", "postinstall"];
+const exoticSpecifiers = [
+    "file:",
+    "git:",
+    "http:",
+    "https:",
+    "link:",
+];
+export function getTrustedDependencies(pkg) {
+    if (pkg.trustedDependencies === undefined) {
+        return [];
+    }
+    if (!Array.isArray(pkg.trustedDependencies)) {
+        throw new Error("package.json trustedDependencies must be an array.");
+    }
+    return pkg.trustedDependencies.map((dependency) => {
+        if (typeof dependency !== "string" || dependency.length === 0) {
+            throw new Error("package.json trustedDependencies must contain package names.");
+        }
+        return dependency;
+    });
+}
+function packageNameFromPath(path) {
+    if (!path.startsWith("node_modules/")) {
+        return undefined;
+    }
+    const parts = path.split("/");
+    if (parts[1]?.startsWith("@")) {
+        return parts.length >= 3 ? `${parts[1]}/${parts[2]}` : undefined;
+    }
+    return parts[1] || undefined;
+}
+export function findInstallScriptDependencies(packageLock, trustedDependencies = []) {
+    const trusted = new Set(trustedDependencies);
+    const found = new Set();
+    for (const [path, pkg] of Object.entries(packageLock.packages ?? {})) {
+        if (pkg.link) {
+            continue;
+        }
+        const name = pkg.name ?? packageNameFromPath(path);
+        if (!name || trusted.has(name)) {
+            continue;
+        }
+        const hasInstallScript = pkg.hasInstallScript === true ||
+            installScriptNames.some((scriptName) => typeof pkg.scripts?.[scriptName] === "string");
+        if (hasInstallScript) {
+            found.add(name);
+        }
+    }
+    return [...found].sort((a, b) => a.localeCompare(b));
+}
+export function getSafeInstallConfig(pkg) {
+    if (pkg.blockExoticSubDeps === undefined) {
+        return { blockExoticSubdeps: false };
+    }
+    if (typeof pkg.blockExoticSubDeps !== "boolean") {
+        throw new Error("package.json blockExoticSubDeps must be a boolean.");
+    }
+    return { blockExoticSubdeps: pkg.blockExoticSubDeps };
+}
+function findExoticSubdependencies(packageLock) {
+    const found = [];
+    for (const [path, pkg] of Object.entries(packageLock.packages ?? {})) {
+        if (path === "" || pkg.link) {
+            continue;
+        }
+        const from = pkg.name ?? packageNameFromPath(path) ?? path;
+        for (const [dependency, specifier] of Object.entries(pkg.dependencies ?? {})) {
+            if (exoticSpecifiers.some((prefix) => specifier.startsWith(prefix))) {
+                found.push({ dependency, from, specifier });
+            }
+        }
+    }
+    return found.sort((a, b) => {
+        const byFrom = a.from.localeCompare(b.from);
+        return byFrom === 0 ? a.dependency.localeCompare(b.dependency) : byFrom;
+    });
+}
+export function assertNoBlockedExoticSubdeps(config, packageLock) {
+    if (!config.blockExoticSubdeps)
+        return;
+    const exoticSubdeps = findExoticSubdependencies(packageLock);
+    if (exoticSubdeps.length === 0)
+        return;
+    const lines = exoticSubdeps
+        .map(({ dependency, from, specifier }) => `  ${from} -> ${dependency}: ${specifier}`)
+        .join("\n");
+    throw new Error(`Blocked exotic subdependencies:\n${lines}`);
+}
+function readJsonFile(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function readPackageLock() {
+    if (!existsSync("package-lock.json")) {
+        throw new Error("package-lock.json not found. Run npm install once with scripts disabled first.");
+    }
+    return readJsonFile("package-lock.json");
+}
+function readPackageJson() {
+    return existsSync("package.json") ? readJsonFile("package.json") : {};
+}
+function run(command, args) {
+    const result = spawnSync(command, args, {
+        stdio: "inherit",
+        shell: process.platform === "win32",
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+function printHelp() {
+    console.log(`safe-install
+
+Usage:
+  safe-install          Run npm install with scripts disabled, then rebuild trusted dependencies
+  safe-install find     List dependencies that declare install-time scripts
+`);
+}
+export function findCommand() {
+    const dependencies = findInstallScriptDependencies(readPackageLock(), getTrustedDependencies(readPackageJson()));
+    if (dependencies.length === 0) {
+        console.log("No untrusted dependencies with install-time scripts found.");
+        return;
+    }
+    console.log("Dependencies with install-time scripts:");
+    for (const dependency of dependencies) {
+        console.log(`  ${dependency}`);
+    }
+    console.log("");
+    console.log("Review these packages before adding them to trustedDependencies.");
+}
+export function installCommand() {
+    const pkg = readPackageJson();
+    const config = getSafeInstallConfig(pkg);
+    const trustedDependencies = getTrustedDependencies(pkg);
+    run("npm", ["install", "--ignore-scripts"]);
+    if (existsSync("package-lock.json")) {
+        assertNoBlockedExoticSubdeps(config, readPackageLock());
+    }
+    if (trustedDependencies.length > 0) {
+        run("npm", ["rebuild", "--ignore-scripts=false", ...trustedDependencies]);
+    }
+}
+export function main(args = process.argv.slice(2)) {
+    const [command] = args;
+    if (command === undefined) {
+        installCommand();
+        return;
+    }
+    if (command === "find") {
+        findCommand();
+        return;
+    }
+    if (command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+if (process.argv[1] && realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    try {
+        main();
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@gkiely/safe-install",
+  "version": "0.1.0",
+  "description": "Run npm installs with lifecycle scripts disabled, then rebuild explicitly trusted dependencies.",
+  "author": "Grant Kiely <grant@youneedawiki.com>",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "npm",
+    "install",
+    "security",
+    "supply-chain",
+    "trusted-dependencies"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "packageManager": "npm@11.9.0",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/gkiely/safe-install.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gkiely/safe-install/issues"
+  },
+  "homepage": "https://github.com/gkiely/safe-install#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "blockExoticSubDeps": true,
+  "bin": {
+    "safe-install": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "latest"
+  }
+}