npm-time-machine-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Lo Pinto
+
+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,213 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MarcoLoPinto/npm-time-machine-cli/main/assets/logo.png" width="300"/>
+</p>
+
+<h1 align="center">NTM: NPM Time Machine</h1>
+
+Reproduce your npm dependency tree as it existed at a specific point in time.
+
+## 🚀 Why?
+
+Supply chain attacks and breaking changes often come from newly published versions of dependencies.
+
+`npm-time-machine-cli` lets you:
+
+- Install dependencies as they existed in the past
+- Avoid recently introduced malicious or unstable versions
+- Reproduce old environments reliably
+
+## ⚡ Features
+
+- 🔙 Time-based dependency resolution
+- 📦 Works with all dependencies (including sub-dependencies)
+- 🛡️ Reduces exposure to recent supply chain attacks
+- 🔍 Verify installed packages against a date
+- 🧹 Reset project state easily
+
+## 📦 Installation
+
+```bash
+npm install -g npm-time-machine-cli
+```
+
+Or use with `npx`:
+
+```bash
+npx npm-time-machine-cli <command>
+```
+
+## 🎯 Usage
+
+### 1️⃣ Set Target Date
+
+First, specify the date you want to freeze dependencies to:
+
+```bash
+ntm set 2024-01-15
+```
+
+This saves your target date to `.npm-time-machine/config.json`.
+
+### 2️⃣ Install Dependencies
+
+Install packages using the frozen date:
+
+**Install all dependencies from `package.json`:**
+```bash
+ntm install
+```
+
+**Install specific packages:**
+```bash
+ntm install express lodash
+```
+
+Only versions published **before or on** the target date will be installed.
+
+**Options:**
+- `--fallback` - If no version exists before the date, use the oldest available version
+  ```bash
+  ntm install --fallback
+  ```
+- `--allow-prerelease` - Include pre-release versions (e.g., alpha, beta, rc) in version resolution
+  ```bash
+  ntm install --allow-prerelease
+  ```
+
+### 3️⃣ Verify Packages
+
+Check if your `package-lock.json` matches the target date:
+
+```bash
+ntm verify
+```
+
+This will warn you about any packages installed **after** your target date.
+
+**Override date temporarily:**
+```bash
+ntm verify 2023-06-01
+```
+
+### 4️⃣ Reset Configuration
+
+Remove ntm configuration:
+
+```bash
+ntm reset
+```
+
+## 📚 Examples
+
+### Scenario 1: Install dependencies from 2 years ago
+
+```bash
+ntm set 2024-01-01
+ntm install
+# Your project now has all dependencies as they existed on Jan 1, 2024
+```
+
+### Scenario 2: Use fallback for legacy packages
+
+```bash
+ntm set 2020-05-15
+ntm install --fallback
+# If a package didn't exist by May 2020, uses its oldest version
+```
+
+### Scenario 3: Verify a historic lock file
+
+```bash
+ntm verify 2023-12-31
+# Checks if package-lock.json complies with Dec 31, 2023 timeline
+```
+
+## 🔧 How It Works
+
+1. **Proxy Server** - Starts a local npm registry proxy on a random port
+2. **Version Filtering** - Intercepts npm requests and filters available versions by publish date
+3. **Registry Redirect** - npm CLI uses the proxy instead of the real registry
+4. **Caching** - Responses are cached to reduce registry calls
+5. **Cleanup** - Proxy automatically closes after installation
+
+### Strict vs Fallback Mode
+
+- **Strict (default)** - Fails if no version exists before the target date
+- **Fallback** - Uses the oldest available version as a last resort
+
+## ⚠️ Important Notes
+
+- **Requires Node 18+** - Uses ES modules
+- **Local Proxy** - Creates a temporary local server (doesn't modify global npm config)
+- **Package Lock** - Works best with existing `package-lock.json` (or `npm-shrinkwrap.json`)
+- **Offline** - Still requires internet to fetch package metadata
+- **Transitive Dependencies** - Automatically handles sub-dependencies
+
+## 🐛 Troubleshooting
+
+### "No config found. Run 'ntm set <date>' first"
+You haven't set a target date yet. Run:
+```bash
+ntm set YYYY-MM-DD
+```
+
+### "No versions available before selected date"
+The package didn't exist on that date. Use:
+```bash
+ntm install --fallback
+```
+
+### "npm install failed"
+The proxy closed unexpectedly. Check:
+- Internet connection
+- npm is properly installed
+- No processes hogging ports
+
+### Port-related errors
+The proxy randomly selects ports. If you get port errors, try again—it should work on retry.
+
+## 📋 Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `ntm set <date>` | Set target date (YYYY-MM-DD format) |
+| `ntm install [packages...]` | Install with frozen timeline |
+| `ntm install --fallback` | Install with fallback mode enabled |
+| `ntm install --allow-prerelease` | Install including pre-release versions |
+| `ntm verify [date]` | Verify packages match a date |
+| `ntm reset` | Remove ntm configuration |
+
+## 🛡️ Security Considerations
+
+- **Supply Chain Protection**: Lock dependencies to a known-safe date before attacks occurred
+- **Audit Checking**: Always run `npm audit` after installation
+- **Trust Verification**: Verify publication dates match expectations
+- **Locked Dependencies**: Use `npm ci` instead of `npm install` in CI/CD
+
+## 👤 Author
+
+Marco Lo Pinto
+
+## 🤝 Contributing
+
+Contributions welcome! Feel free to open issues or submit pull requests on GitHub.
+
+
+## ⚡ Quick Start
+
+```bash
+# 1. Install globally
+npm install -g npm-time-machine-cli
+
+# 2. Set a date in your project
+cd your-project
+ntm set 2024-06-01
+
+# 3. Install dependencies
+ntm install
+
+# 4. Verify everything is correct
+ntm verify
+```
+
+You now have a reproducible, time-locked dependency tree! 🎉

package/bin/ntm.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { createRequire } from "module";
+import { saveConfig, loadConfig } from "../src/config.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const program = new Command();
+
+program
+    .name("ntm")
+    .description("npm time machine")
+    .version(version);
+
+// SET
+program
+    .command("set")
+    .argument("<date>", "Target date (YYYY-MM-DD)")
+    .description("Set the target date for dependency resolution")
+    .action((date) => {
+        const targetDate = new Date(date);
+
+        if (isNaN(targetDate)) {
+            console.error("❌ Invalid date");
+            process.exit(1);
+        }
+
+        saveConfig({ date });
+        console.log(`✔ Date set to ${date}`);
+    });
+
+// INSTALL
+program
+    .command("install")
+    .argument("[packages...]", "Packages to install")
+    .option("--fallback", "Allow fallback to oldest version if none match date")
+    .option("--allow-prerelease", "Include pre-release versions in version resolution")
+    .description("Install dependencies using frozen time")
+    .action(async (packages = [], options) => {
+        try {
+            const { startProxy } = await import("../src/proxy.js");
+            const { runInstall } = await import("../src/installer.js");
+
+            const { date } = loadConfig();
+            const targetDate = new Date(date);
+
+            console.log(`⏳ Installing with frozen date ${date}`);
+            console.log(`⚙️  Mode: ${options.fallback ? "fallback" : "strict"}${options.allowPrerelease ? ", prerelease enabled" : ""}`);
+
+            const proxy = await startProxy(targetDate, {
+                allowFallback: options.fallback || false,
+                allowPrerelease: options.allowPrerelease || false
+            });
+
+            try {
+                const args = ["install"];
+
+                if (packages.length > 0) {
+                    args.push(...packages);
+                }
+
+                await runInstall(proxy.port, args);
+
+            } finally {
+                proxy.close();
+            }
+
+        } catch (err) {
+            console.error(`❌ ${err.message}`);
+            process.exit(1);
+        }
+    });
+
+// VERIFY
+program
+    .command("verify")
+    .argument("[date]", "Optional date override")
+    .description("Verify installed dependencies against a date")
+    .action(async (dateArg) => {
+        try {
+            const { verifyProject } = await import("../src/verify.js");
+
+            let date;
+
+            if (dateArg) {
+                date = new Date(dateArg);
+            } else {
+                const config = loadConfig();
+                date = new Date(config.date);
+            }
+
+            if (isNaN(date)) {
+                console.error("❌ Invalid date");
+                process.exit(1);
+            }
+
+            await verifyProject(date);
+
+        } catch (err) {
+            console.error(`❌ ${err.message}`);
+            process.exit(1);
+        }
+    });
+
+// RESET
+program
+    .command("reset")
+    .description("Remove ntm configuration")
+    .action(async () => {
+        const { resetProject } = await import("../src/reset.js");
+        await resetProject();
+    });
+
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "npm-time-machine-cli",
+  "version": "1.0.0",
+  "description": "Install npm dependencies as they existed at a given date",
+  "type": "module",
+  "bin": {
+    "ntm": "bin/ntm.js"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.js"
+  },
+  "author": "Marco Lo Pinto",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarcoLoPinto/npm-time-machine-cli.git"
+  },
+  "homepage": "https://github.com/MarcoLoPinto/npm-time-machine-cli#readme",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^11.0.0",
+    "express": "^4.18.2",
+    "node-fetch": "^3.3.2",
+    "semver": "^7.6.0"
+  },
+  "preferGlobal": true,
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "npm",
+    "dependencies",
+    "time",
+    "reproducibility",
+    "deterministic",
+    "lockfile",
+    "versioning",
+    "supply-chain",
+    "security",
+    "cli",
+    "dev-tools"
+  ]
+}

package/src/cache.js

@@ -0,0 +1,11 @@
+// Cache module
+
+const cache = new Map();
+
+export function getCache(key) {
+    return cache.get(key);
+}
+
+export function setCache(key, value) {
+    cache.set(key, value);
+}

package/src/config.js

@@ -0,0 +1,21 @@
+import fs from "fs";
+import path from "path";
+
+const dir = path.join(process.cwd(), ".npm-time-machine");
+const file = path.join(dir, "config.json");
+
+export function saveConfig(config) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir);
+    }
+
+    fs.writeFileSync(file, JSON.stringify(config, null, 2));
+}
+
+export function loadConfig() {
+    if (!fs.existsSync(file)) {
+        throw new Error("No ntm config found. Run 'ntm set <date>' first.");
+    }
+
+    return JSON.parse(fs.readFileSync(file));
+}

package/src/installer.js

@@ -0,0 +1,25 @@
+import { spawn } from "child_process";
+
+export function getNpmCommand() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+export function runInstall(port, args = ["install"]) {
+    return new Promise((resolve, reject) => {
+        const command = getNpmCommand();
+        const child = spawn(
+            command,
+            [...args, "--registry", `http://localhost:${port}`],
+            { stdio: "inherit" }
+        );
+
+        child.on("error", (error) => {
+            reject(error);
+        });
+
+        child.on("close", (code) => {
+            if (code === 0) resolve();
+            else reject(new Error("npm install failed"));
+        });
+    });
+}

package/src/proxy.js

@@ -0,0 +1,108 @@
+import express from "express";
+import fetch from "node-fetch";
+import { getCache, setCache } from "./cache.js";
+import { filterVersionsByDate, updateDistTags } from "./version-filter.js";
+import { pipeline } from "stream";
+import { promisify } from "util";
+
+const streamPipeline = promisify(pipeline);
+
+export async function startProxy(targetDate, options = {}) {
+    const { allowFallback = false, allowPrerelease = false } = options;
+
+    const app = express();
+
+    app.get("/*", async (req, res) => {
+        try {
+            const url = `https://registry.npmjs.org${req.url}`;
+
+            // Check if this is a tarball request
+            if (req.url.endsWith(".tgz")) {
+                const response = await fetch(url);
+
+                if (!response.ok) {
+                    return res.status(response.status).send("Upstream error");
+                }
+
+                res.status(response.status);
+
+                const excludedHeaders = ["content-encoding", "transfer-encoding"];
+
+                response.headers.forEach((value, key) => {
+                    if (!excludedHeaders.includes(key.toLowerCase())) {
+                        res.setHeader(key, value);
+                    }
+                });
+
+                try {
+                    await streamPipeline(response.body, res);
+                } catch (err) {
+                    console.error("Stream error:", err.message);
+                }
+
+                return;
+            }
+
+            // Metadata request (JSON)
+            const cached = getCache(req.url);
+            if (cached) {
+                return res.json(cached);
+            }
+
+            const response = await fetch(url);
+
+            if (!response.ok) {
+                return res.status(response.status).send("Upstream error");
+            }
+
+            const data = await response.json();
+
+            // filter versions
+            const filterResult = filterVersionsByDate(data, targetDate, {
+                allowFallback,
+                allowPrerelease
+            });
+
+            if (filterResult === null) {
+                console.error(
+                    `❌ No versions available before ${targetDate.toISOString()} for ${req.url}`
+                );
+                return res
+                    .status(404)
+                    .send("No valid versions before selected date");
+            }
+
+            if (filterResult.fallback) {
+                console.warn(`⚠ No versions before date for ${req.url}`);
+                console.warn(`⚠ Fallback to oldest version: ${filterResult.fallbackVersion}`);
+            }
+
+            // Update data with filtered versions
+            data.versions = filterResult.versions;
+
+            // Update dist-tags
+            updateDistTags(data, filterResult);
+
+            // set cache
+            setCache(req.url, data);
+
+            res.json(data);
+
+        } catch (err) {
+            console.error(`❌ Proxy error for ${req.url}:`, err.message);
+
+            return res.status(502).send("Bad gateway");
+        }
+    });
+
+    const server = app.listen(0);
+    const port = server.address().port;
+
+    console.log(`⏳ NTM proxy running on http://localhost:${port}`);
+    console.log(`⚙️  Mode: ${allowFallback ? "fallback enabled" : "strict"}${allowPrerelease ? ", prerelease enabled" : ""}`);
+
+    return {
+        port,
+        close: () => server.close()
+    };
+}

package/src/reset.js

@@ -0,0 +1,13 @@
+import fs from "fs";
+import path from "path";
+
+export async function resetProject() {
+    const dir = path.join(process.cwd(), ".npm-time-machine");
+
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        console.log("✔ Removed ntm configuration");
+    } else {
+        console.log("Nothing to reset");
+    }
+}

package/src/verify.js

@@ -0,0 +1,123 @@
+import fs from "fs";
+import fetch from "node-fetch";
+import semver from "semver";
+
+export function extractPackageName(packagePath) {
+    if (!packagePath || packagePath === "") {
+        return null;
+    }
+
+    const marker = "node_modules/";
+    const markerIndex = packagePath.lastIndexOf(marker);
+
+    if (markerIndex === -1) {
+        return packagePath;
+    }
+
+    return packagePath.slice(markerIndex + marker.length) || null;
+}
+
+function collectFromPackageEntries(packages) {
+    const collected = [];
+
+    for (const [packagePath, info] of Object.entries(packages)) {
+        if (!info?.version || !semver.valid(info.version)) continue;
+
+        const packageName = extractPackageName(packagePath);
+        if (!packageName) continue;
+
+        collected.push({ name: packageName, version: info.version });
+    }
+
+    return collected;
+}
+
+function collectFromDependencyTree(dependencies, collected = []) {
+    if (!dependencies) {
+        return collected;
+    }
+
+    for (const [name, info] of Object.entries(dependencies)) {
+        if (info?.version && semver.valid(info.version)) {
+            collected.push({ name, version: info.version });
+        }
+
+        collectFromDependencyTree(info?.dependencies, collected);
+    }
+
+    return collected;
+}
+
+export function collectLockfilePackages(lock) {
+    if (lock.packages && typeof lock.packages === "object") {
+        return collectFromPackageEntries(lock.packages);
+    }
+
+    if (lock.dependencies && typeof lock.dependencies === "object") {
+        return collectFromDependencyTree(lock.dependencies);
+    }
+
+    return [];
+}
+
+export async function verifyProject(date) {
+    if (!fs.existsSync("package-lock.json")) {
+        throw new Error("No package-lock.json found");
+    }
+
+    const lock = JSON.parse(fs.readFileSync("package-lock.json", "utf-8"));
+    const packages = collectLockfilePackages(lock);
+
+    let issues = 0;
+    const metadataCache = new Map();
+    const lookupFailures = [];
+    const seen = new Set();
+
+    for (const pkg of packages) {
+        const key = `${pkg.name}@${pkg.version}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+
+        let data = metadataCache.get(pkg.name);
+
+        try {
+            if (!data) {
+                const res = await fetch(`https://registry.npmjs.org/${pkg.name}`);
+                if (!res.ok) {
+                    throw new Error(`Registry responded with ${res.status}`);
+                }
+
+                data = await res.json();
+                metadataCache.set(pkg.name, data);
+            }
+
+            const publishTime = data.time?.[pkg.version];
+
+            if (!publishTime) {
+                lookupFailures.push(`${pkg.name}@${pkg.version}`);
+                continue;
+            }
+
+            if (new Date(publishTime) > date) {
+                console.log(`❌ ${pkg.name}@${pkg.version} → ${publishTime}`);
+                issues++;
+            }
+
+        } catch (error) {
+            lookupFailures.push(`${pkg.name}@${pkg.version} (${error.message})`);
+        }
+    }
+
+    if (lookupFailures.length > 0) {
+        const preview = lookupFailures.slice(0, 5).join(", ");
+        throw new Error(
+            `Failed to verify ${lookupFailures.length} package(s): ${preview}`
+        );
+    }
+
+    if (issues === 0) {
+        console.log("✔ All dependencies are within the selected date");
+    } else {
+        console.log(`⚠ Found ${issues} issues`);
+    }
+}

package/src/version-filter.js

@@ -0,0 +1,77 @@
+import semver from "semver";
+
+/**
+ * Filters package versions by a target date
+ * @param {Object} packageData - NPM registry response with versions and time metadata
+ * @param {Date} targetDate - Cutoff date for version filtering
+ * @param {Object} options - Filter options
+ * @param {boolean} options.allowFallback - If true, fallback to oldest version when none match
+ * @param {boolean} options.allowPrerelease - If true, include pre-release versions
+ * @returns {Object} Filtered versions object or null if no versions match
+ */
+export function filterVersionsByDate(packageData, targetDate, options = {}) {
+    const { allowFallback = false, allowPrerelease = false } = options;
+    const { versions, time } = packageData;
+
+    if (!versions || !time) {
+        return null;
+    }
+
+    const filtered = {};
+
+    // Filter versions by publish date
+    for (const [version, publishTime] of Object.entries(time)) {
+        // Skip metadata entries
+        if (["created", "modified"].includes(version)) continue;
+
+        // Check if version exists and meets criteria
+        if (
+            new Date(publishTime) <= targetDate &&
+            versions[version] &&
+            (allowPrerelease || !semver.prerelease(version))
+        ) {
+            filtered[version] = versions[version];
+        }
+    }
+
+    // Handle no versions before date
+    if (Object.keys(filtered).length === 0) {
+        if (allowFallback) {
+            const allVersions = Object.keys(versions || {});
+            const oldest = allVersions.sort(semver.compare)[0];
+
+            if (oldest) {
+                return {
+                    versions: { [oldest]: versions[oldest] },
+                    fallback: true,
+                    fallbackVersion: oldest
+                };
+            }
+            return null;
+        }
+        return null;
+    }
+
+    return { versions: filtered, fallback: false };
+}
+
+/**
+ * Updates dist-tags in package metadata based on filtered versions
+ * @param {Object} packageData - NPM registry response
+ * @param {Object} filteredResult - Result from filterVersionsByDate
+ * @returns {Object} Updated package data
+ */
+export function updateDistTags(packageData, filteredResult) {
+    if (!filteredResult || !filteredResult.versions) {
+        return packageData;
+    }
+
+    const versions = Object.keys(filteredResult.versions);
+    if (versions.length > 0) {
+        const latest = versions.sort(semver.rcompare)[0];
+        packageData["dist-tags"] = packageData["dist-tags"] || {};
+        packageData["dist-tags"].latest = latest;
+    }
+
+    return packageData;
+}